Describe the surface in model-readable metadata, don't direct the model

[aterga]

Summary

The server instructions and the served tool descriptions told a model how to work: START WITH open_app, ALWAYS call this FIRST, NEVER guess a domain, "web search the official URL", a numbered seven-step flow across tools, and a routing chain to run before answering anything. Both directories read these fields, and both prohibit a description that steers the model rather than describing the tool — so every surface now describes what it is, what it returns, what it rejects, and what it requires.

What a caller needs is kept, and after review the emphasis moved: both directories expect a description to say when a tool applies and what is unsafe to pass, so the rule this PR enforces is not "no guidance" but "none of the five manipulations the directories actually prohibit" — unrelated behavioral instructions, overly broad triggering, preference over or interference with other tools, calls to unrelated external software, and hidden or obfuscated instructions.

The second half of the PR became an accuracy pass. Review turned up a recurring defect — metadata claiming more than the code does — and every instance found is fixed and listed below.

Stacked on #163 (base is that branch, so the diff shows this change alone; GitHub retargets to main when #163 merges). It rewrites the same regions #163 touched — the update-call description and the instructions' policy paragraph — so branching off main would have lost that work.

Related issues

None — follow-up in the directory-submission series.

Changes

• Server instructions: 10005 → ~3600 characters. What remains is a description: where textual Candid applies (and where it does not), what the two tool families act on, what a derivation origin is and which reads it gates, the two Internet Identity access levels, how canister values are stored, the financial-transactions policy (stated as policy — the base branch removed the copy of compliance.rs's method families and canister scopes, and this branch takes that rewrite verbatim), and where building and deploying happen. Gone: the START WITH entry-point rule, the routing chain, the numbered "Typical flow", the locale-conversion directives, "web search or ask the user", and the caps imperatives.
• All 11 served descriptions rewritten as capability statements. canister_query loses its "start with open_app first" preamble; open_app loses its ROUTING block; resolve_app and discover_app_canisters lose the "NEVER guess / web search" rules. open_app carries, per review, the one constraint the runtime cannot enforce: pass the user's app name unchanged, pass only a URL the user supplied or one from a verified official source, and do not construct a domain from the name — because the IC-evidence check shows a domain is served from the Internet Computer, not that it is the app the user meant.
• Argument and reply schemas follow the same rule (calls.rs, discover.rs, identities.rs): imperatives become plain statements, and "or ask the user for it" becomes what actually provides the value.
• Accuracy fixes, all found in review and each verified against the handler first. The IC-evidence refusal was asserted unconditionally in six places when it fires only where the derivation origin must be assumed — a declared origin is never probed. discover_app_canisters claimed a refusal it does not perform (it returns an empty result). get_canister_api_doc promised a structured result "in every case", in its description and again in its root schema. retry: true was presented as a diagnosis, though an unreadable interface and a rejecting or trapping method both set it. api_doc_available was presented as "a guide is returned" when it reports a declaration — corrected on get_canister_candid, open_app, the DiscoveredCanister schema, and the runtime notes. ResolveAppOutput.alternative_origins was attributed to the application origin, though it is read from the derivation origin. canister_query promised a did-you-mean repair on any empty OQL result, when it needs an unknown start and a schema read that returns entities. get_canister_oql_schema's whole schema documented an anonymous path the handler rejects. Three tools did not disclose their session prerequisite. The identity-mismatch note claimed a wrong derivation origin when a different account or Internet Identity produces the same difference. And the access levels govern only calls signed with the session's delegation, not every update call — which was also wrong in both submission documents' reviewer procedures, where a reviewer following the step would not have seen the promised behavior.
• New test model_readable_metadata_respects_marketplace_policy scans the server instructions, all 11 descriptions, and every argument and reply schema for those five prohibited categories. It checks each schema's decoded strings rather than its JSON serialization — escaping turns an invisible character into printable ASCII, which would split a banned phrase and pass the character check — matches phrases on collapsed whitespace, and allows only printable ASCII plus the three punctuation marks the metadata actually uses, so no invisible character can ride along. A second test, open_app_metadata_forbids_a_constructed_domain, pins the safeguard above on both surfaces a model reads before calling.
• Submission docs state the real rule (descriptions explain when a tool applies; the five prohibited manipulations) rather than "must not manipulate how the model works", record the guessed-identifier posture, and drop a stale line claiming the instructions "prime the assistant".

Out of scope: the 13 deferred IcProtocolTools descriptions are not served and are unchanged. Two behavior changes review raised are deliberately not here, since they are not metadata: classifying retryable agent errors, and extending the IC-evidence probe to declared derivation origins.

Testing

• cargo build --locked --all-targets
• cargo test --workspace — 146 core + 52 / 10 / 9 / 20 / 1, all green
• cargo clippy --workspace --all-targets — unchanged 10-warning baseline (this repo is not rustfmt-clean; no repo-wide cargo fmt, matching prior PRs)
• npm test --prefix monitoring/mcp-status (dashboard unchanged)

Checklist

• I have read the Contributing guidelines.
• Docs (README / comments) updated for any user-visible change.
• No secrets, credentials, or internal-only information are included.

---

Generated by Claude Code

---

Generated by Claude Code

[aterga]

CI is red on aa71657, and it is not this PR's failure.

The failing check is CI / test, on one live-network test:

discover::tests::search_finds_ckusdc_and_lookup_identifies_it
lookup: "dashboard request failed: error sending request for url
(https://ic-api.internetcomputer.org/api/v3/canisters/xevnm-gaaaa-aaaar-qafnq-cai)"

The IC dashboard API is down — that URL returns HTTP 524 and then times out on three consecutive direct attempts from here. This PR changes tool descriptions, the server instructions, and argument-schema documentation; it changes no request path. The same test failed at the same time on #164, an unrelated diff, and this branch's own previous head (30850a0) passed CI at 10:56Z, before the outage.

Nothing to port and nothing to weaken: the test asserts against a live service, and relaxing it to survive an outage would cost the assertion its value. The re-run waits for the dashboard; a check-in is scheduled and will report back here only if the result is anything other than green.

For the record, the head also carries a merge of this PR's base branch (#163's c90baaf), so the diff shown here stays limited to the metadata change.

---

Generated by Claude Code

[Copilot]

Pull request overview

Reframes MCP metadata as factual capability descriptions rather than model directives.

Changes:

• Rewrites server, tool, and argument descriptions.
• Adds a regression test for directive wording.
• Updates directory-submission documentation.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
docs/openai-directory-submission.md	Documents OpenAI metadata compliance.
docs/anthropic-directory-submission.md	Documents Anthropic metadata posture.
crates/imcp2-core/src/tools.rs	Rewrites served metadata and adds testing.
crates/imcp2-core/src/identities.rs	Revises resolver argument metadata.
crates/imcp2-core/src/discover.rs	Revises discovery argument metadata.
crates/imcp2-core/src/calls.rs	Revises call argument metadata.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[aterga]

Requesting changes on three points:

1. P1 — Restore the no-fabricated-domain safeguard.
   In [OpenAppArgs](https://github.com/dfinity/imcp2/blob/6c50d6a1219078c97cd64b3f13f0466dbc97fe99/crates/imcp2-core/src/discover.rs#L1827-L1837), add:

   If the user supplied only an app name, pass that name unchanged. Only pass a URL supplied by the user or obtained from a verified official source; do not construct a domain from the name.

   Add the same constraint to open_app’s description and a regression assertion. The runtime check proves that a domain uses ICP, not that an ICP-hosted lookalike belongs to the intended app. OpenAI specifically says required identifiers must not depend on model guessing. [OpenAI tool guidance](https://developers.openai.com/plugins/plan/tools)

2. P1 — Replace the blanket “no directives” test with a narrower marketplace-policy test.
   [model_readable_metadata_states_capabilities_not_directives](https://github.com/dfinity/imcp2/blob/6c50d6a1219078c97cd64b3f13f0466dbc97fe99/crates/imcp2-core/src/tools.rs#L2501-L2569) prohibits legitimate invocation and safety guidance. Both marketplaces expressly expect descriptions to explain when tools apply. [OpenAI](https://developers.openai.com/plugins/plan/tools), [Anthropic](https://claude.com/docs/connectors/building/review-criteria)

   Change it to reject only:

   • Unrelated behavioral instructions.
   • Overly broad triggering.
   • Preference over or interference with other plugins/tools.
   • Calls to unrelated external software.
   • Hidden or obfuscated instructions.

   Preserve tool-local prerequisites, selection criteria, and safety constraints. Update both submission documents accordingly; “must not manipulate how the model works” overstates OpenAI’s actual rule.

3. P2 — Correct the identity-mismatch diagnosis.
   The claims in [get_app_principal](https://github.com/dfinity/imcp2/blob/6c50d6a1219078c97cd64b3f13f0466dbc97fe99/crates/imcp2-core/src/tools.rs#L908-L910) and [list_app_accounts](https://github.com/dfinity/imcp2/blob/6c50d6a1219078c97cd64b3f13f0466dbc97fe99/crates/imcp2-core/src/tools.rs#L964-L966) incorrectly say a browser mismatch means the derivation origin is wrong.

   Replace with:

   A difference from the browser may indicate a different derivation origin, selected account, or Internet Identity; compare those inputs before retrying.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Suppressed comments (1)

docs/anthropic-directory-submission.md:368

• canister_update_call cannot perform lifecycle management calls as claimed here. Its raw update path does not set an effective canister ID (calls.rs:1522-1532), while management-canister lifecycle calls explicitly require the target via with_effective_canister_id (management.rs:324-328). Remove this parenthetical so reviewers are not told to expect an unsupported capability.

>    connector, with the icp CLI. (The generic `canister_update_call` can
>    still reach management methods on a canister your principal controls.)

[claude]

Answering the suppressed finding from the latest review, which has no thread of its own — and it was the most valuable one in the round, because it caught an error I introduced myself.

canister_update_call cannot perform lifecycle management calls as claimed here. Its raw update path does not set an effective canister ID (calls.rs:1522-1532), while management-canister lifecycle calls explicitly require the target via with_effective_canister_id (management.rs:324-328).

Verified and correct. raw_call issues agent.update(&canister, method) with no with_effective_canister_id, so an ingress call to aaaaa-aa carries aaaaa-aa as its effective canister id, while management.rs's mgmt_call sets .with_effective_canister_id(target) — and that function's own doc comment says why: "the boundary node requires this for lifecycle methods". Those calls are rejected before a replica sees them.

How it got there is worth stating plainly. Two rounds ago review flagged "creating, funding, and managing canisters is done by the user with the icp CLI" as an overclaim, because the generic update-call tool restricts nothing about the target canister. I checked the guard, saw no restriction on aaaaa-aa, and widened the text to say management lifecycle methods stay reachable — without checking the agent call path, where the actual block lives. So I replaced one inaccuracy with another, in a compliance document, while fixing inaccuracies.

Fixed on the base branch in 5363586 and merged here in 83a53e8. All three sites that carried my claim — the Anthropic posture bullet, its reviewer step 4, and the OpenAI posture bullet — now state that the update-call path is not a route to canister management, and give the mechanism (the effective canister id it does not set) so a reviewer can check it rather than take it on trust.

---

Generated by Claude Code

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Suppressed comments (3)

crates/imcp2-core/src/tools.rs:1987

• “Per-app data is gated by the calling principal” is broader than the implementation and conflicts with the new DiscoveredCanister documentation, which correctly says method names establish neither storage nor canister-side gating. Only this connector's OQL paths unconditionally require a delegated principal; Candid method reads may remain anonymous. Attribute the gate to the OQL tool path rather than to all per-app data.

    An app's derivation origin is the exact origin Internet Identity derives the user's principal from. It is not necessarily the app's visible URL, and an alternative-origins entry does not identify it; open_app and resolve_app resolve it, and the identity-bearing tools take the origin itself rather than a URL. There is no on-chain name-to-URL directory: open_app matches a name against a built-in registry of well-known apps, and where the derivation origin would have to be assumed from the URL itself, open_app and resolve_app refuse an origin with no evidence of being an Internet Computer app, while discover_app_canisters returns an empty result for such a domain. Per-app data is gated by the calling principal, so OQL reads require a derivation origin and reject an anonymous read. Account delegations are short-lived and derived on demand from this connection's standing Internet Identity credential, which is obtained at connect time and lasts for the chosen session duration (up to 30 days). Internet Identity's consent screen offers two access levels, and they govern the calls signed with that session's account delegation — the ones that carry a derivation origin: on a \"Questions only\" session those reads work and those update calls are rejected by the network, while \"Actions & questions\" permits both. A call made with no derivation origin is not signed with the delegation at all; it runs as the anonymous principal, so those access levels do not govern it. This server's own checks still do — the financial-transactions guard runs before any identity or network work, so a call it refuses is refused whether or not an origin was passed — and past that the canister decides whether to accept it.\n\n\

crates/imcp2-core/src/tools.rs:595

• This repeats the unsupported claim that per-app data itself is principal-gated. The implementation only establishes that this connector rejects anonymous OQL requests; the canister may expose public data, and the same tool allows anonymous Candid reads. Describe the enforced OQL prerequisite without inferring the canister's storage or authorization behavior from the schema/execute names.

        description = "Read from an Internet Computer canister with either a Candid `query` method or an OQL query — exactly one of the two. `method` is a query function from the canister's Candid interface, invoked with textual-Candid `args`; `oql` is an OQL query as a JSON object string, run against the canister's `execute` method as plain JSON with no Candid escaping. Canisters that expose OQL (get_canister_candid reports `oql: true`) reject a Candid `method` data query and are read through `oql`; a plain query canister such as a ledger takes `method`. The `oql` path requires `derivation_origin` — per-app data is gated by the caller's principal, and an anonymous OQL read is rejected — and returns `columns` and `rows` (a markdown table) with `has_more` for paging; on an empty result it re-reads the schema for this principal and, when that read returns entities and the query's `start` is not one of them, returns `valid_entities` plus a did-you-mean repair; a `start` that does exist, an empty schema, or a schema read that fails leave both out. The `method` path may be anonymous, or take `derivation_origin` and `account` to read as the user's account, and returns the decoded reply in textual Candid. Reading as the user's account — the whole `oql` path, and the `method` path when given a `derivation_origin` — requires an authenticated session; an anonymous `method` read does not. `derivation_origin` is resolved by open_app or resolve_app rather than being a raw URL, and the OQL entity and field names come from get_canister_oql_schema. State changes go through canister_update_call.",

crates/imcp2-core/src/tools.rs:248

• This also attributes the authentication requirement to the schema/canister, although the code only proves that this connector rejects a missing origin before making any call (tools.rs:268-274). Keep the prerequisite, but state it as connector behavior so the metadata does not infer canister-side gating from the OQL method names.

        description = "Fetch the OQL schema catalogue of a canister that exposes the OQL surface (get_canister_candid reports `oql: true`): its entities, their primary keys, fields, and edges, as JSON, plus a ready-to-run canister_query example per entity (each preserving this call's identity). Entity names are the schema's own, often plural and different from the Candid types and methods (e.g. `bookings`, not `Booking`/`getBookings`). `derivation_origin` is required: the schema is gated by the caller's principal, so a read with no origin is rejected with guidance rather than returning an empty entity list. Since every read here is made as the user's app account, it requires an authenticated session. The origin is the app's canonical Internet Identity derivation origin, which open_app and resolve_app resolve; the reply echoes `derived_for_origin` and `acted_as_principal`.",

The merge-base changed after approval.

[claude]

Answering the three suppressed findings from the latest review, which have no threads of their own. All three were right, and they name the same defect this branch created.

The corrected DiscoveredCanister docs now say that two method names establish neither what a canister stores nor how it authorizes callers — while SERVER_INSTRUCTIONS, canister_query's description and get_canister_oql_schema's description still asserted "per-app data is gated by the caller's principal" as fact. So the PR contradicted itself, and a directory reviewer comparing the two would have seen it.

What is actually enforced is narrower and entirely ours: this server rejects an OQL read with no derivation origin. A canister may serve public data, and a Candid method read may be anonymous — as the same tool's description already says.

Fixed in 2ba5e93 at all seven sites, each now attributing the rule to the connector: the server instructions, icp_oql_guide's served text, canister_query's and get_canister_oql_schema's descriptions, OqlSchemaArgs.derivation_origin, CanisterQueryOutput.is_anonymous, and both README passages. Three implementation comments (tools.rs:474, tools.rs:713, calls.rs:915, plus discover.rs:114) keep the shorthand on purpose: they are neither served to a model nor published, so they are notes about the code, not claims in metadata. Say so if you'd rather they matched.

On the approval. @sea-snake, this push resets your approval, and I want to be straight about the trade. The base branch was squash-merged, so this PR had to merge main regardless and the reset was already unavoidable; the seven corrections rode along at no extra cost rather than waiting for a second reset. Workspace green (52 + 7 + 10 + 149 + 21 + 1), clippy at the 10-warning baseline, and the PR is mergeable against main again.

---

Generated by Claude Code

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.