MCP Pill

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

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds useful context beyond those: results are 'bounded' and 'payload-free', which tells the agent it won't get an unbounded stream or heavy payloads. It does not describe ordering, but that is minor for a read-only tail operation.

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 one short, front-loaded sentence with no filler or repetition. Every word earns its place, and the most important qualifiers ('bounded', 'payload-free') come immediately after the verb.

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 simple read-only tool with one optional parameter, full safety annotations, and no output schema, the description plus schema is nearly sufficient. The only meaningful gap is the lack of guidance on when to use audit.tail versus audit.verify or other siblings.

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 0% and the description does not explicitly explain the 'limit' parameter. However, 'bounded' hints at the parameter's roleaine, and the schema's minimum/maximum constraints make the parameter self-explanatory for a simple optional limit. More explicit mapping from 'bounded' to 'limit' would have been better.

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 ('read'), resource ('decision receipts'), and scope ('from this process'), and the qualifiers 'bounded' and 'payload-free' make the operation more concrete. It does not explicitly name a sibling or contrast with audit.verify, so it falls just short of full differentiation.

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 states what the tool does but gives no guidance about when to choose audit.tail over audit.verify or any other sibling. There are no exclusions, prerequisites, or alternative references, so the agent must infer usage from the name alone.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile, so the bar is lower. The description adds the 'payload-free' qualifier as minor context but does not describe failure behavior, output, or what verification entails. No contradiction with annotations.

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?

A single sentence with zero filler, front-loading the verb and resource. It is efficient, though the brevity edges toward under-specification.

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 tool with one required, undocumented array parameter and no output schema, the description is too terse. An agent cannot determine what valid 'events' input looks like, what a successful verification returns, or how the hash chain is structured.

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 0% and the description does not explain the required 'events' parameter — not what the array objects must contain, not how they relate to the hash chain. 'Payload-free' hints at content but does not compensate for the missing parameter documentation.

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 ('Verify') and resource ('audit hash chain'), with the qualifying term 'payload-free' adding scope. It is clearly distinguishable from the closest sibling audit.tail, though the phrasing is somewhat jargon-heavy.

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?

No guidance is given on when to use this tool versus siblings like audit.tail or messages.validate, and no when-not-to-use conditions or alternatives are mentioned. The agent must infer suitability from the name alone.

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 readOnlyHint, idempotentHint, and non-destructive. The description adds the behavioral detail that no provider is executed, which reinforces this, but does not disclose additional traits such as rate limits, transient failures, or what 'upper-bound' assumptions are made.

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?

A single, compact sentence with no filler. The action and primary constraint are front-loaded.

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?

Despite low complexity in prose, the tool has 6 required, undocumented parameters and no output schema. The description gives no clues about parameter roles or the shape of the estimate, leaving an agent under-equipped 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 description coverage is 0% and the description names no parameters. An agent cannot infer the meaning of duration_seconds, variants, commercial_rate_cents_per_second, gpu_rate_cents_per_hour, fixed_cost_cents, or retry_limit from the description or 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 ('Estimate'), a clear resource ('commercial and local upper-bound cost'), and a distinguishing constraint ('without executing a provider'). This separates it from sibling tools like community.preview and policy.evaluate.

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 phrase 'without executing a provider' conveys when it should be used (before execution, for cost estimation) and implicitly that it is not for actually running operations. However, it does not name alternatives or give explicit exclusion criteria, so it stops short of full routing guidance.

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 readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds a genuinely useful behavioral fact beyond the annotations: the plugin is NOT executed, only inspected. No contradiction with annotations.

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?

One short sentence with the verb and object front-loaded, followed by a meaningful qualifier. No filler, redundancy, or restating of the tool name.

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?

This is a simple single-parameter tool and the description covers purpose and a key behavioral trait. But with no output schema, it doesn't indicate what 'inspect' returns (configuration, status, metadata?), and usage guidance is thin. Adequate but with a real gap.

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 0%, so the description must compensate. It gives plugin_id semantic meaning by naming the target as a 'declarative plugin record,' implying the parameter identifies such a record. However, it does not explain ID format, defaults, or lookup behavior, so compensation is partial.

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 uses a specific verb and resource ('Inspect one declarative plugin record') and adds a clarifying negative ('without executing it'). This plainly distinguishes it from catalog.search (which searches) and policy.evaluate (which evaluates/executes).

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 phrase 'without executing it' implies this is the tool for read-only inspection rather than execution, and the readOnlyHint supports that. However, it never explicitly names sibling tools or states conditions like 'use when you need to see the record but not run it.'

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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds valuable context: 'no plugin is loaded' clarifies that the tool does not execute plugin code, and 'untrusted' signals that the results should be treated with caution. This goes beyond the annotations and is behaviorally informative.

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 a single, dense sentence that immediately communicates the core action and key caveat. There is no wasted wording, and the most important information (returns briefs, no plugin loaded) is front-loaded. It is a model of conciseness.

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?

The tool has two parameters, one required, and no output schema. The description does not describe the return format of the briefs (fields, structure) nor clarify parameter semantics. Given that annotations cover safety, the description still leaves the agent unsure about what constitutes a valid query and what the result will look like, which is a significant gap for a search 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 0%, so the schema provides no semantic meaning for 'query' or 'limit'. The description does not explain what the query should contain (e.g., a search term, plugin name, etc.) or what the limit controls. The agent is left to infer parameter semantics from the tool name alone, which is insufficient.

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') and resource ('plugin briefs'), and adds a crucial qualifier ('compact', 'untrusted', 'no plugin is loaded') that clarifies the nature of the result and the side-effect-free behavior. It is distinct from siblings like catalog.inspect which likely provides detailed inspection.

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 no explicit guidance on when to use this tool versus alternatives. It does not mention conditions for use, exclusions, or alternative tools. The phrase 'no plugin is loaded' hints at a safety context but does not explain when this tool is preferred over catalog.inspect or others.

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 readOnlyHint=true and destructiveHint=false, so the agent knows the tool is safe and side-effect free. The description adds one useful behavioral detail ('never processes a payment') that goes beyond the raw annotations, but it does not cover other behavioral aspects like return format, auth requirements, or the meaning of the 25/75 split.

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 a single, tightly packed sentence with no filler. It front-loads the main action and immediately follows with a critical negative constraint, making it highly efficient and well-structured.

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 tool with two required parameters (one an untyped array of objects) and no output schema, the description is incomplete. It does not clarify what '25/75' means, what the contributions array should look like, or what the preview returns, and it does not resolve ambiguity against the sibling budget.preview.

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 0%, so the description must compensate by explaining parameter semantics. It fails to explain what 'contributions' should contain, how 'gross_revenue_cents' relates to the 25/75 allocation, or the expected structure of the array. The vague '25/75 contribution allocation' does not provide actionable parameter-level 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 states a specific action ('Preview a 25/75 contribution allocation') and explicitly negates payment processing, giving agents a clear sense of the tool's core purpose. However, it does not explicitly differentiate from the sibling budget.preview, relying on the tool name to convey the domain distinction.

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 offers no explicit guidance on when to use this tool versus alternatives like budget.preview or policy.evaluate. 'Never processes a payment' implies a non-payment context but never names a condition or alternative tool, leaving usage decisions 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the scope is 'local governed-catalog state,' which is useful context, but it does not describe what the report contains or any additional behavioral traits.

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 a single sentence with no filler, front-loading the core purpose immediately. It is appropriately sized for a zero-parameter tool and every word contributes meaning.

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 zero-parameter tool with annotations covering the safety profile, the description is largely complete enough to invoke. The only minor gap is that it does not hint at what the returned state will contain, but the low complexity and absence of an output schema make this non-critical.

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 tool has zero parameters and the schema coverage is trivially 100%, so the description does not need to explain parameters. Baseline 4 for zero-parameter tools is appropriate; no additional parameter information is needed.

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 ('Report') and a specific resource ('local governed-catalog state'), which makes the tool's basic purpose clear. It distinguishes it from search/inspect siblings by focusing on state reporting, but it does not explicitly contrast it with any sibling or define what 'health' means.

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?

There is no guidance on when to use this tool versus the sibling tools. The description implies it is a status/health check, but it does not state conditions, alternatives, or exclusions, leaving the agent to infer usage.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. However, it adds no behavioral detail about what validation entails, whether failures are silent or throw, or what traceability guarantees exist, so it offers little beyond the annotations.

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 a single sentence with no redundant content. It is front-loaded with the action and resource, though the terms 'traceable operational' add vagueness rather than precise meaning.

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 the opaque nested object and lack of an output schema, the description is incomplete. An agent still does not know what content the message must contain, what a successful validation looks like, or how the result is returned. The annotations cover the safety profile but not the operational semantics.

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 0%, and the only parameter, 'message', is an opaque object with no documented nested properties. The description hints that the message should be an 'envelope', but it does not explain the required fields, traceability metadata, or accepted formats, so the agent cannot construct a valid input beyond providing any object.

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 clear verb ('validate') and names a resource ('traceable operational message envelope'), but the resource is jargon and is never defined. It does not distinguish this from sibling tools like audit.verify or catalog.inspect, which could also involve validation-style checks.

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 no guidance on when to use this tool or when to prefer one of the sibling tools. There are no exclusions, prerequisites, or scenario-based instructions, leaving the agent to infer applicability from the tool's name alone.

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 indicate readOnlyHint, idempotentHint, and destructiveHint=false, and the description adds meaningful behavioral context beyond them: fail-closed behavior and a firm 'never dispatches the plugin.' These traits are important for an agent deciding whether invoking this tool has side effects.

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 entire description is one tightly written sentence with no filler. The most important behavioral fact, fail-closed preflight, comes first, and the side-effect exclusion is stated immediately after. Every word 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 simple two-parameter tool with strong annotations, the description covers core safety behavior. However, there is no output schema and the description does not state what the tool returns or how the fail-closed result is represented, which is a meaningful gap for an agent that needs to interpret the evaluation outcome.

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 0%, and the description does not explain either parameter. While the names plugin_id and approval_present are somewhat self-explanatory, the description does not clarify how approval_present interacts with fail-closed behavior or what values are expected, so it fails to compensate for the missing schema descriptions.

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 clearly defines the tool as a 'policy preflight' that is 'fail-closed' and clarifies it 'never dispatches the plugin,' which states a specific operation and a key non-behavior. It does not explicitly name a sibling or differentiate itself from the listed alternatives, so it stops short of a 5.

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 term 'preflight' implies the tool should be used before dispatching or relying on a plugin, and 'fail-closed' signals a safety-check context. However, there is no explicit guidance on when to prefer this tool over alternatives or when not to use it, leaving usage mostly inferred.

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