Diogenes Agent Guardrails & Sandbox MCP

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

Beyond readOnly/idempotent/non-destructive annotations it discloses statelessness, a 32 KB payload cap, 60 RPM rate limit, payment options (demo=true or L402 at 25 sats), and the HTTP 400 failure mode for invalid input. These are operational traits the annotations cannot express and materially affect how an agent calls it.

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-loads purpose, then routing, then operational constraints — a sensible order with no filler sentences. The final clause is dense (size, rate, auth, error all in one line), which slightly hurts scannability but every element earns its place.

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 2-param read-only audit tool with an output schema, the description covers purpose, alternative routing, payload limits, auth/payment, and error behavior — everything needed to invoke it correctly. Nothing material 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% and the audit_profile enum is fully documented, so the schema carries most weight. The description still adds value by noting manifest_json accepts a JSON string or object form and that audit_profile 'defaults to strict', reinforcing default behavior beyond the enum list.

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 (Scans) and resource (external MCP server's initial tools/list manifest), and names the exact threat classes detected (tool-name shadowing, hidden prompt-injection directives). It explicitly distinguishes itself from the closest sibling detect_mcp_schema_rugpull, so an agent can route without opening either 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?

Gives an explicit when-to-use condition (vetting a newly discovered third-party MCP server before mounting) and an explicit when-to-use-the-other condition (comparing a pinned baseline against a live mid-session tools/list → detect_mcp_schema_rugpull). Alternatives and exclusions are both named.

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 read-only/idempotent/non-destructive, and the description adds operationally important traits those annotations cannot express: a 32 KB input ceiling, 60 RPM rate limit, HTTP 400 on invalid input, and a payment/demo access mode (L402, 15 sats). This is exactly the added context the dimension rewards.

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 purpose in the first clause, then usage, then operational constraints — a sensible information order. It is dense and slightly crammed with parentheticals, but nearly every clause carries actionable 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?

An output schema exists so return values need no explanation, and the description still covers invocation preconditions, limits, error signaling, and payment handling. Nothing an agent needs to call this 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% and it documents both parameters and the enum, so the baseline is 3. The description adds value by restating the egress_policy default and, more usefully, disclosing a '?demo=true' / L402 access mechanism that appears nowhere in the input 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 ('static validation firewall') and a precise resource ('outbound network destination URIs') plus the exact threat classes blocked (169.254.169.254, RFC 1918, query-string secrets). It explicitly names the sibling it is not (verify_agent_command_safety), so an agent can distinguish it without opening 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 an explicit trigger ('Use when validating a user-supplied or tool-supplied URI destination before network dispatch') and an explicit exclusion routing to verify_agent_command_safety for local shell commands or general prompts. Both when-to-use and the alternative are stated.

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?

The annotations already establish the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real operational context: a 32 KB payload cap, 60 RPM, a stateless edge call, L402 payment of 25 sats or '?demo=true', and an HTTP 400 on invalid input. The one flaw is the claim that "'context' defaults to 'standard'", which is misleading, because the schema marks context as required and no such default exists.

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 tool's purpose is front-loaded in the first sentence, followed by usage, the sibling exclusion, and constraints. The final sentence crams four unrelated facts (size cap, rate limit, payment, error code) into one clause, but there's 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?

Given that an output schema exists, the description needn't explain return values, and it covers the operational envelope (limits, auth/payment, failure mode) that an agent needs before calling. The gaps are the undocumented strictness parameter behavior and the inaccurate 'context' default, both of which an agent would rely on.

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 each of the three parameters is already documented in the schema, and the baseline of 3 applies. The description restates parameter purpose loosely and introduces a default for 'context' that contradicts the required list, but it never touches the 'strictness' enum (exact_entailment / semantic_paraphrase / citations_only), which is where added semantics would have mattered most.

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 gives a specific verb and resource: cross-references factual claims, numbers, and citations in a draft response against retrieved source passages and flags hallucinations. That is far more concrete than the name alone. It only differentiates itself from one sibling (sanitize_tool_output_stream) and says nothing about the near-identical sibling verify_factual_claims, so an agent can't fully separate the two from this text.

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?

It states an explicit trigger ('before returning it to the user' / 'before delivery') and names an alternative with the condition that selects it: use sanitize_tool_output_stream for prompt-injection and invisible Unicode scrubbing. However, the closest alternative, verify_factual_claims, is never mentioned, leaving the most likely routing ambiguity unresolved.

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 readOnly/idempotent/non-destructive annotations, it discloses statelessness, a 32 KB payload cap, 60 RPM rate limit, demo and L402 (15 sats) access paths, and an HTTP 400 failure mode for invalid input — operationally useful facts an agent cannot infer from structured fields.

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 purpose and sibling routing before operational details, with no filler. The final sentence is dense with comma-spliced constraints (size, rate, auth, error code), which is efficient but slightly overpacked.

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 and annotations carrying the safety profile, the description still covers the limit, auth, and error behaviors an agent needs before calling. Everything required to invoke it correctly is present, apart from the default-value defect noted above.

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 would be 3, but the description actively misleads: it says 'sensitivity' defaults to 'strict_2_repeats' while the schema says it defaults to 'standard_3_repeats' when omitted. That direct conflict on the one behavioral knob can cause an agent to assume a stricter threshold than the server actually 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 (analyzes an agent's recent tool-call trace) plus the three concrete failure patterns it detects: identical retry spins, A/B state oscillation, and runaway token burn. It also names the sibling verify_agent_command_safety and the scope that separates them, so an agent can route without opening either 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?

Explicitly says when to use it ('monitoring autonomous agent execution loops to decide whether to continue or trip a token-burn breaker') and names the alternative for the adjacent case ('for inspecting a single command payload for security threats before execution, use verify_agent_command_safety instead'). Both the include and exclude conditions are stated.

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?

The description provides critical behavioral traits beyond the annotations, including resource limitations (32 KB, 60 RPM), operational mode (Stateless read-only edge call), and specific failure modes (HTTP 400 if invalid). This level of detail is essential for an agent operating in a system integrity context.

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 definition is dense and highly technical, which is appropriate for its subject matter. While long, every phrase serves a functional purpose, successfully front-loading the primary goal and scoping constraints within the initial sentences.

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?

Given its high complexity and focus on security, the description is nearly exhaustive. It covers input requirements, operational limits, error handling, use cases, and explicit differentiation from related tools, leaving no critical operational gaps.

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?

Although the schema coverage is 100%, the description adds significant semantic context. It clarifies the functional role of the inputs (baseline is the trusted past, live is the current measurement) and details advanced invocation parameters like the use of 'demo=true' and specific payment units (L402).

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 purpose is highly specific: it computes structural differences between a pinned baseline and a live response. It clearly states the outcome—catching mid-session description or schema tampering—which is distinct from general auditing functions like `audit_mcp_server_manifest`.

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 usage guidelines are explicitly defined by the operational context. It identifies the primary use case (mid-session verification) and provides a direct alternative sibling tool for a related but different use case (first-time static security audit).

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?

Adds genuinely useful operational context beyond the annotations: 32 KB payload cap, 60 RPM rate limit, stateless edge call, no host filesystem, HTTP 400 on invalid input, demo/MPP payment path. However it never explains what the AST audit actually rejects at runtime (blocklist behavior, false-positive handling) or whether execution results include partial output on timeout. The readOnly/idempotent claims are consistent with the annotations but are simply restated, so the surplus value is mostly limits rather than semantics.

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 and the sibling differentiation, with no filler sentences. The final sentence crams limits, defaults, payment modes, and error codes into one long clause, which costs some scannability.

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 two-parameter tool with an output schema, the description covers what an agent needs to call it correctly: isolation guarantees, size/rate limits, default profile, payment/demo affordance, and failure signaling. Return-value explanation is correctly omitted since the output schema carries it.

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?

The description says timeout_profile 'defaults to fast_1s', while the schema description says it 'defaults to standard_5s when omitted'. That is a direct conflict on the most consequential parameter, and an agent trusting the prose would mis-size execution ceilings. Otherwise the prose just restates python_script and the enum, both of which the 100% coverage schema already documents.

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 (audit + execute Python source) plus the execution mechanism (AST-governed WebAssembly sandbox, no host filesystem). It explicitly contrasts itself with the sibling verify_agent_command_safety, so an agent can route between them without opening either 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?

Gives a positive trigger (executing LLM-generated Python snippets safely) and a named alternative with the discriminating condition (checking shell commands without executing). The routing decision is fully determined by the description.

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 read-only, idempotent, non-destructive, closed-world behavior, but the description adds substantial operational context beyond that: stateless edge call, max 32 KB payload, 60 RPM rate limit, payment options (?demo=true or L402 at 25 sats), and HTTP 400 on invalid input.

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?

Three sentences, zero waste, and front-loaded with the core purpose and sibling distinction before operational limits. Every clause carries useful information.

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 explained. The description covers size limits, rate limits, auth/payment paths, default behavior, and error handling, which is complete for an agent 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 both parameters are already documented there, including the redaction_style enum and its default. The description mostly restates the default and text input, adding no syntax or format details 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?

States the specific verb 'redacts' and enumerates the exact resource classes (emails, phone numbers, SSNs, credit cards, API keys, crypto private keys), and explicitly distinguishes itself from the sibling sanitize_tool_output_stream by naming the different use case.

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?

Explicitly says when to use it ('stripping personal data or secret credentials from prompts, logs, or outbound messages') and names the alternative tool plus the condition that selects it (neutralizing indirect prompt injections and invisible Unicode in inbound tool responses).

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, non-destructive), and the description goes well beyond them by disclosing the 32 KB payload ceiling, 60 RPM rate limit, auth paths (?demo=true or L402 at 15 sats), and the HTTP 400 failure mode for invalid input. That is exactly the operational context an agent needs before calling a metered edge endpoint.

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?

Purpose, threats, usage, alternative, and operational limits are all front-loaded and each clause carries information. It is a dense semicolon-chained paragraph, however, and the trailing auth/error clause could be tightened without losing anything.

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, and the description still covers the input contract, size and rate limits, payment path, and error behavior. Nothing material for correct invocation is missing given the annotations and schema richness.

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 both parameters are already documented in structured form, which sets the baseline at 3. The description only references 'raw_tool_output' and never explains wrap_tag or what the isolation wrappers mean for prompt safety, and the phrase "(with enum defaults)" attaches the enum to the wrong parameter, adding a small amount of confusion rather than meaning.

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 names a specific verb ("Sanitizes") and enumerates the exact threats removed: Unicode Tag characters U+E0000, Markdown tracking-image beacons, and indirect prompt overrides. It explicitly routes the PII case to the sibling redact_sensitive_pii, so an agent can separate this from the other ~90 tools 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?

It states the trigger condition precisely ("cleaning raw third-party tool outputs or scraped web text before inserting it into the LLM context window") and names the alternative for the adjacent use case ("for redacting personal identifiable information ... use redact_sensitive_pii instead"). Both when-to-use and when-to-use-something-else are explicit.

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 say read-only, idempotent, non-destructive, but the description adds substantial operational context the agent cannot get from them: statelessness, a 32 KB payload cap, 60 RPM rate limit, auth via '?demo=true' or L402 (20 sats), and the HTTP 400 failure mode. That is exactly the kind of beyond-schema behavior disclosure this dimension rewards.

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?

Two dense sentences that front-load the purpose, then usage routing, then constraints; very little waste. The parenthetical constraint block (limits, auth, error code) is packed tightly but remains scannable.

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 only 2 params, full schema coverage, a rich annotation set and an output schema, the description covers nearly everything an agent needs to call it correctly. The one gap is the wrong stated default for max_tokens_ceiling, which should be reconciled with the schema.

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 would be 3, but the description actively conflicts with the schema: it claims 'max_tokens_ceiling' defaults to '512', while the schema says it 'defaults to 2048' when omitted. That contradiction is worse than silence, since an agent may assume a tighter quota than is actually applied.

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 ('Audits inbound MCP sampling/createMessage callbacks') and names the two concrete threats it blocks (includeContext='allServers' snooping and token quota hijacking). It is unmistakable against siblings like sanitize_tool_output_stream or audit_mcp_server_manifest.

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 use condition ('when filtering a connected MCP server's request to sample the host LLM') and explicitly routes the adjacent case elsewhere ('for scrubbing text returned from a standard synchronous tools/call response, use sanitize_tool_output_stream instead'). The when/when-not split is fully resolved in the 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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds genuinely new operational context: statelessness, a 32 KB input cap, 60 RPM rate limit, an L402 payment path (15 sats), a '?demo=true' mode, and HTTP 400 on invalid input. These are exactly the constraints an agent needs and are not derivable from annotations or schema.

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?

Two dense sentences, front-loaded with the verb and compliance guarantee, followed by routing and operational limits — no wasted framing. The payment/rate-limit clause is packed tightly mid-sentence, which slightly hurts scannability but every element carries information.

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, and the description still covers the remaining gaps an agent would hit: input size ceiling, throughput limit, payment mechanics, and error signaling (HTTP 400). Nothing needed to invoke it 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 description coverage is 100%, so the baseline is 3; the description modestly exceeds it by restating the 'sql_statement' and default-'postgres' dialect behavior and by surfacing the '?demo=true' selector, which is not represented in the input schema at all. No syntax or size-per-dialect guidance beyond the 32 KB cap.

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 ('static AST syntax tree parsing on SQL statements') plus the exact success condition ('verify strictly read-only SELECT clauses') and failure modes rejected (mutations, stacked queries, comment bypasses). An agent can immediately tell this apart from synthesize_sql_query or transpile_sql_dialect.

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?

Explicitly says when to use it ('verifying that an agent-authored SQL statement is strictly read-only before running it on a database') and names an alternative for out-of-scope input ('use verify_agent_command_safety instead'). It does not address the closely overlapping sibling audit_sql_injection_ast, whose injection-rejection remit overlaps the 'stacked queries or comment bypasses' language, leaving one ambiguity unresolved.

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, non-destructive, closed-world), but the description adds material operational detail annotations cannot express: a 32 KB payload ceiling, a 60 RPM rate limit, the default trust_policy, the '?demo=true'/L402 15-sat access path, and an HTTP 400 on invalid input. That is exactly the kind of cost, limit, and failure-mode disclosure the description is supposed to carry.

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 purpose and the sibling routing before the operational details, which is the right ordering. The second half is dense — size, rate limit, parameters, default, demo/L402, and error code packed into one sentence — costing a little scannability but no clause 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 no explanation, and the description still flags the HTTP 400 failure path. For a two-parameter read-only validator, every decision an agent needs — when to call it, what to pass, defaults, limits, and cost — is present.

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% and the enum is documented, so the schema already does the semantic work; baseline 3 applies. The description does restate the trust_policy default and add the non-schema '?demo=true' access flag, but it adds no meaning about what the three policies actually accept or reject.

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 ('Verifies a remote agent's A2A /.well-known/agent.json discovery card') and enumerates the exact checks performed (JWS/DID signature binding, HTTPS enforcement, capability spoofing). It explicitly names the closest sibling, audit_mcp_server_manifest, and the axis that distinguishes them (peer agent card vs. MCP tools/list manifest).

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 trigger ('Use when authenticating a peer autonomous agent before delegating subtasks or exchanging payments over A2A') and an explicit exclusion with the correct alternative for the MCP-manifest case. Nothing is left to inference about when to reach for this tool versus its nearest sibling.

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?

Goes well beyond the annotations (which already declare readOnly, idempotent, non-destructive, closed-world): it discloses statelessness, a 32 KB payload ceiling, a 60 RPM rate limit, the demo/L402 pricing path, and the HTTP 400 failure mode for invalid input. These are exactly the operational constraints an agent cannot infer from structured fields.

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-loads the action and the sibling differentiation, then compresses pricing/limits/errors into one trailing sentence — efficient overall. The final clause is somewhat dense with operational trivia (L402, 20 sats, 20 s timeout) that slightly crowds the core guidance, but nothing is wasted.

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, return-value detail is correctly omitted, and the description still covers the constraints that block a correct call: size cap, rate limit, auth/payment options, and error behavior. Nothing an agent needs before invoking 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% and already documents both fields, including the 'bash_command' default. The description restates the default and names the payload field but adds no new syntax, size-per-field, or format guidance beyond the schema, so the baseline of 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 (evaluates/blocks) against specific resources (untrusted prompts, bash commands, tool arguments) and names the exact threat classes it addresses (prompt injection, destructive shell commands, key exfiltration). It also explicitly contrasts itself with validate_sql_query_ast, so an agent can route correctly without opening either 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?

Gives a positive trigger ('use when screening a general shell command or user prompt before autonomous agent execution') and a negative one with the named alternative ('for statically validating SQL database queries at the AST level, use validate_sql_query_ast instead'). Both the when-and the when-not are explicit.

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