Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations: names what is overwritten (one file in the local state directory, replacing any earlier approval for this server id), the WARDEN_ALLOW_PIN_CHANGES=1 precondition, the no-network/no-launch guarantee, and the refusal conditions. The one muddy point is that it says repeating the same call is refused, which sits awkwardly beside idempotentHint=true and could confuse an agent deciding whether to retry — not a clean contradiction, but it costs a point.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the outcome, then cleanly sectioned into when-to-use, when-not-to-use, behaviour, returns, and a call example — easy to scan for a six-parameter tool. Minor redundancy: the 'approval cannot override a block' point is made in the opening and then again in the when-not-to-use list.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, gate-checked write with a nested schema and an output schema, the description covers everything an agent needs to call it correctly: the prerequisite read, the verbatim hash hand-off, the environment precondition, the staleness refusal, and the side effects. Return values are left to the output schema, as appropriate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics: it identifies which fields must be copied verbatim from the status_mcp_server response, explains that previous_pin_revision is null when no approval is stored, and states these values act as a concurrency guard so two reviewers cannot overwrite each other. That tie between parameters and the refusal rule is not in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (store an operator approval for tool definitions and launch identity) plus the downstream effect: later vet_mcp_server calls treat them as approved and report change as drift. It is immediately distinguishable from revoke_mcp_server (removing) and status_mcp_server (reading state), both of which it names.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'When to use' gate (after a human reviewed status_mcp_server output and agreed) and an explicit 'When NOT to use' list covering self-initiated approval, trying to unblock a blocked server, removal, and inspection — each with the correct sibling named. The required hand-off of currentToolsHash/currentIdentityHash/previousRevision from the prior status call is spelled out as a precondition.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, the description reveals local/no-network operation, the exact failure mode (isError with CanonicalizationCode, no partial bytes), accepted input forms (parsed value or JSON string parsed with parseJsonStrict), and strict acceptance rules (integers within ±(2^53−1), lone surrogates refused). No annotation contradiction is present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized with clear sections: purpose, when to use, when not to use, behavior, return shape, and example. Every sentence carries useful information, and the core purpose is front-loaded before the usage guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with an output schema, the description fully covers usage context, input constraints, failure behavior, and expected output. Nothing an agent needs to call or interpret the result correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds meaning by specifying that a string input is parsed with parseJsonStrict first, and it provides a concrete example (canonicalize_json({ value: { b: 1, a: 2 } }) → {"a":2,"b":1}) that clarifies input and output shape beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Return'), a specific resource (RFC 8785 JSON Canonicalization Scheme serialization), and the purpose (WARDEN threat-feed signatures, tool-def pins, byte-checking). It also distinguishes the tool from static_scan_tools in the 'When NOT to use' section, so it is not just a restatement of the name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description contains dedicated 'When to use' and 'When NOT to use' sections. It lists concrete use cases (publishing/verifying signed threat feeds, hashing tool defs, comparing JSON documents independent of key order) and names an existing alternative (static_scan_tools) plus an exclusion (pretty-printing for humans).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Even with annotations declaring readOnlyHint, idempotentHint, and destructiveHint, the description adds substantial behavioral context: local URL parse, no DNS/HTTP, fail-closed empty allowlist, case-insensitive matching, wildcard semantics, and refusal of unparseable URLs. This fully discloses the tool's operational behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized into short labeled sections, front-loads the core purpose, and contains no filler. Each sentence adds meaningful guidance, from scope and exclusions to behavior and return shape.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only, idempotent two-parameter tool, the description is complete: it explains purpose, when to use it, when not to use it, behavior, return value, and an example. The existing output schema covers the detailed return structure, so no necessary information is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents both parameters thoroughly. The description adds value beyond this with a concrete example call, wildcard behavior restated in practical terms, and the fail-closed empty allowlist note, which helps the agent form correct invocations.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Ask EgressGuard whether a URL's hostname is on an operator allowlist.' It clearly distinguishes itself from siblings by naming vet_mcp_server, static_scan_tools, and canonicalize_json as tools not to use for this purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit 'When to use' and 'When NOT to use' sections, naming concrete alternatives and explaining the intended context: checking a host before a tool fetches or posts. It also specifies what the tool does NOT do, such as fetching the URL or inspecting tool text.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish readOnly/idempotent/non-destructive/no-open-world, and the description adds real context on top: 'local glob match, no network', empty patterns mark every tool safe, whole-name matching, and an explicit negative ('does not call Warden.vet and does not persist anything'). It also clarifies the consequence that sensitive tools stay advertised and require per-call approval, which the annotations do not convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core classification purpose, then organized into labelled When to use / When NOT to use / Behaviour / Returns / Example blocks. Every sentence carries distinct information (scope, exclusions, matching semantics, non-persistence, return shape) with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be re-explained, yet the description still names the shape { sensitive, safe }. Combined with the matching semantics, the empty-patterns edge case, the example call, and the explicit statement that this tool does not run or persist anything, an agent has everything needed to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantic value beyond the schema: case-insensitivity, whole-name matching, '*' as the only wildcard, the empty-array edge case, and a concrete wildcard example ('*delete*' hits create_delete_repo). That said, it mostly restates the patterns parameter rather than clarifying the tools array.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('split advertised tool names into sensitive vs safe') plus the mechanism (case-insensitive globs from policy.sensitiveToolPatterns). It also explicitly scopes itself as 'policy over identifiers, not an injection scan', which cleanly separates it from sibling scanners like static_scan_tools and vet_mcp_server.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Contains explicit 'When to use' (show the user which names need confirmation before approving a server, or preview a glob set) and 'When NOT to use' sections that name the alternative tools and the condition for each (static_scan_tools/vet_mcp_server for poisoning, check_egress_url for URL policy). Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive and openWorld=false, so safety is covered. The description still adds real value: local compiled snapshot, no network, no mutation, and the exact digest construction (sha256 over RFC 8785 of {version, fold, rules}). It could go slightly further on payload size/version availability, so not a full 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Structured and front-loaded: what it returns, then when/when-not, then behaviour and an example. Dense but each section earns its place; the digest-format sentence is slightly heavy for a listing tool but is meaningful for reproducibility.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, yet the description still characterizes the ruleset identity and reproducibility guarantee. Combined with the explicit routing to alternatives and the flag semantics, an agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the include_source description already does baseline work. The description adds meaning beyond the schema by tying include_source=true to the use case of independently re-implementing/re-running the pattern and to payload size, which helps an agent decide the flag rather than just parse it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Return) and resource (the in-force static-scan ruleset) and enumerates its contents. It explicitly distinguishes itself from siblings static_scan_tools and vet_mcp_server, so an agent knows it lists the table rather than applying it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit 'When to use' cases (explain a finding code, confirm ruleset v14, re-run a scan) and an explicit 'When NOT to use' that names the two alternative tools and the condition that selects them. Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations flag the operation as destructive and non-read-only, and the description goes well beyond that: it discloses that exactly one local state file is deleted, that the action is irreversible except by re-approval, that it requires WARDEN_ALLOW_PIN_CHANGES=1, that no network or tools payload is involved, and the response shape. This is rich context beyond the hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core effect, then structured into When-to-use / When-NOT / Behaviour / Returns. Despite its length, each sentence carries distinct operational information with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers prerequisites, preconditions, failure conditions (refused if the approval changed), reversibility, environment gating, and even the return value (redundant given the output schema, but harmless). Nothing an agent needs to call it safely is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the previous_pin_revision concurrency semantics and every server field are already documented in the schema itself. The description largely restates these (including the example payload) rather than adding new meaning, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Delete the stored approval for one server id') and immediately differentiates its effect from sibling tooling ('vet_mcp_server treats the server as never seen: its tools are unpinned again'). An agent can distinguish it from approve_mcp_server and status_mcp_server without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'When to use' and 'When NOT to use' sections name the exact alternatives for each excluded case: approve_mcp_server for changed servers, threat feed/policy for blocking, status_mcp_server for inspection. It also prescribes the prerequisite step (take previousRevision from status_mcp_server first).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), and the description still adds real context beyond them: local regex+guard evaluation with no network and no mutation, advisory-tier hits flagged advisory=true and excluded from the score, no server launch and no tool output sent to a model. That is exactly the extra behavioral surface annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded purpose followed by clearly labelled When to use / When NOT to use / Behaviour / Returns blocks; every line is substantive. It runs longer than strictly necessary, but the structure makes scanning cheap and no sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be detailed, and the description still points to it ('structured JSON matching outputSchema') plus the ruleset digest. For a single-parameter, read-only scan tool this covers everything an agent needs to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the nested field descriptions are thorough, so the schema carries most of the burden. The description still adds value by enumerating the scanned surface (name, description, input schema, title, output schema, annotations, extension metadata), noting text is folded first, and supplying a concrete example invocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (run the static-scan gate) plus concrete scope: ruleset v14, 36 signatures, applied to every advertised tool field. It explicitly separates itself from vet_mcp_server, classify_sensitive_tools and list_scan_rules, so an agent can pick it without opening sibling schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use ('you have a tools/list dump and want injection / credential / hidden-Unicode hits without origin, pinning, or the threat feed') and when-not-to-use with three named alternatives mapped to their distinct conditions. Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, and the description goes further: it names the exact file location (WARDEN_STATE_DIR, default ~/.local/state/warden/pins), states it writes nothing, makes no network call, never launches the target server, and works regardless of WARDEN_ALLOW_PIN_CHANGES. It also discloses the shape of the return (stored approval or null, revision, hashes, field-by-field diff) and whether the process can mutate approvals.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then organized into labelled When to use / When NOT to use / Behaviour sections plus a compact example. Every sentence carries a fact an agent could act on; nothing is restated from the schema or annotations without added detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description does not need to enumerate return fields, and it still summarizes them at a level useful for routing. For a read-only comparison tool with nested parameters, it covers side effects, state location, downstream consumption, and exclusions completely.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: it explains that the tools payload and launch identity you pass are hashed into currentToolsHash/currentIdentityHash, which are the exact values approve/revoke require. A worked example call shows the intended shape concrete. It stops short of per-field guidance, which the schema already carries.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("read the approval WARDEN has stored for one server id") plus what it is compared against. It explicitly distinguishes itself from vet_mcp_server, which is named as the tool that runs gates while this one runs none.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit "When to use" (before approve/revoke decisions, to diff since last approval, show the operator reviewText) and an explicit "When NOT to use" naming vet_mcp_server. It also names the sibling tools whose inputs this tool supplies (currentToolsHash, currentIdentityHash, previousRevision).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, closed-world, non-destructive), yet the description adds substantial non-obvious behavior: local/deterministic/no-network, the built-in 11-record threat floor rather than a signed feed, a durable local pin store with first-contact UNPINNED/advisory, origin defaulting to allowUnknownServers=true, and the fact that it never connects to, starts, or approves the target.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then cleanly sectioned when-to-use / when-NOT-to-use / behaviour / returns+example. Dense rather than padded, though it runs long and restates a couple of defaults (e.g. allowUnknownServers=true) that the schema already documents.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an outputSchema present it correctly avoids re-documenting the return shape while still summarizing the verdict fields, and it covers the identity/pinning/threat-feed semantics and policy defaults an agent needs to call this correctly. Nothing material is missing for a three-param, nested-object tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the three parameters (server, tools, policy) and every nested field are already documented in the schema; baseline 3 applies. The description adds a worked example invocation and a note that policy can be overridden with the host's real knobs, but no parameter syntax beyond what the schema carries.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (vet/run), the exact resource (WARDEN's ordered gate chain over a server identity plus its tools/list payload), and enumerates what the verdict contains. It also differentiates itself from siblings by naming the four gates and pointing to the tools that do partial work.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'When to use' with the precondition (a complete server record, wanting the host's pre-exposure decision) and a 'When NOT to use' section that routes each partial case to a named alternative: static_scan_tools, classify_sensitive_tools, check_egress_url, canonicalize_json. Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.