governance-platform

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

Annotations already declare readOnlyHint=true and idempotentHint=true, indicating a safe read operation. The description adds context about the specific data returned (plan, usage, counts, fingerprint), which is useful but does not disclose any limitations, error behavior, or response format beyond that. 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?

The description is a single sentence listing the returned information without filler words, making it compact and easy to scan. It has a minor formatting quirk with a line break and lacks a verb, but it remains appropriately sized and readable.

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 is a simple read-only status query with one parameter and no output schema. The description enumerates the main data categories returned, which gives the agent a clear expectation of the output, even though it does not specify exact structure or data types.

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 input schema fully documents the single api_key parameter with a description of the expected format (gai_...), achieving 100% schema coverage. The tool description adds no additional parameter semantics, so the baseline score of 3 is appropriate.

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 accurately lists the account-specific data returned (plan, key usage, Blueprint counts, build fingerprint), making it distinguishable from sibling tools as the only account status query. However, it lacks an explicit verb like "retrieves" or "gets," relying on a noun phrase, which slightly reduces clarity.

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 provides no explicit guidance on when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. It simply states what the account status contains, leaving the agent to infer appropriate use cases.

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 the tool as read-only, idempotent, and non-destructive. The description adds behavioral context beyond these structured hints: it specifies that no Blueprint is required and describes the analysis as comparing to the 'usual pattern' and identifying 'fields stand out', which helps set expectations. There is 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?

The description is two sentences long, with the first stating the core purpose and the second adding a concise prerequisite note. Every phrase contributes meaning, and the most important information is 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?

The tool has only two parameters and no output schema, so the description carries the responsibility of conveying what to expect. It explains the purpose and implies the output (an explanation of pattern fit and standout fields). While it doesn't detail return format or edge cases, it is reasonably complete for this tool's simplicity.

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 schema already provides 100% coverage with descriptions for both parameters (api_key and structured_data). The description does not add significant extra meaning about the parameters themselves; it only reinforces the record context. Thus the baseline score of 3 is appropriate.

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 states the tool's function with a specific verb ('Explain') and resource ('a record'), and specifies the output: whether it fits the usual pattern and which fields stand out. The note 'No Blueprint required' additionally distinguishes it from sibling tools that may require a Blueprint.

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 provides clear context for when to use the tool (for anomaly explanation) and the prerequisite-condition that no Blueprint is required. However, it does not explicitly name alternative tools or state when not to use this tool, so it lacks explicit exclusions.

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 idempotentHint=true and destructiveHint=false, so the safety profile is known. The description adds that this is a promotion action on discovered rules, but does not disclose additional behavioral traits such as reversibility, side effects, or required permissions. 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 that is front-loaded with the action and resource, then specifies the target state. Zero wasted words; every phrase contributes to understanding the tool's purpose.

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 straightforward state-change tool with full schema coverage and idempotency annotations, the description is sufficiently complete. It doesn't explain output format or failure modes, but those are not essential for the core promotion action. The source-to-target relationship is clearly stated.

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% — every parameter has a description in the schema, including api_key format, rule_id origin, and blueprint default. The description itself does not discuss parameters, but the schema carries the full burden. Baseline 3 is appropriate.

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?

'Promote' is a specific verb, and the description clearly defines the resource ('a rule discovered by discover_patterns') and the outcome ('Blueprint-ready form'). This distinguishes it from sibling tools like reject_rule or create_blueprint, making the tool's purpose unmistakable.

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 implicitly indicates the tool should be used on rules that came from discover_patterns, which provides clear context for when to invoke it. It doesn't explicitly point to alternative tools or state when not to use it, but the prerequisite is unambiguous and sufficient for most usage scenarios.

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?

Description discloses the gate logic: 'authorized=true only on PASS' and 'REVIEW means do not proceed automatically', adding behavioral context beyond the annotations. It does not contradict the idempotentHint or destructiveHint annotations, and clarifies the decision 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?

Two sentences, front-loaded with the core purpose, and ends with a clear differentiation from 'validate'. No fluff or redundancy.

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 3-parameter tool with no output schema, the description covers the essential decision outcomes (authorized vs REVIEW), the validation process, and the distinction from validate. It is slightly lacking in describing error/failure modes, but overall provides sufficient context for an agent.

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 all three parameters. The description adds context that structured_data is validated against the blueprint, but does not provide additional parameter-level meaning beyond what the schema already states.

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?

Description uses a specific verb ('Go/no-go') and clearly identifies the resource ('real-world action' like payment, filing, API write). It distinguishes itself from sibling 'validate' by contrasting the two purposes, making the tool's role unambiguous.

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 states when to use it (before real-world actions) and when not to proceed (REVIEW means do not proceed automatically). It also names the alternative 'validate' and explains the difference, providing clear usage 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 establish read-only and idempotent behavior. The description adds valuable context by specifying output (health verdicts with advice) and highlighting that it catches joint conflicts that pairwise checks miss, going beyond the annotation baseline.

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 sentences, no fluff or redundancy. First sentence states the core purpose, second enumerates output specifics. 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?

Given no output schema, the description adequately explains return values (verdicts and advice). Parameter relationships are handled by schema, and annotations cover safety. Minor gap: no differentiation from related validation tools, but this is not essential for invoking the 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 descriptions cover 100% of parameters, including the distinction between config and blueprint. The description itself adds no parameter-specific meaning, so 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?

Description states a specific verb+resource: 'Static pre-deploy analysis of a Blueprint's rule set', and enumerates concrete health verdict categories (healthy, acceptable, fragile, etc.). This clearly distinguishes it from sibling tools like validate or check_drift, which have different purposes.

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 'pre-deploy' implies usage context, but there is no explicit guidance on when to use this tool versus alternatives like validate or profile_blueprint_robustness. No exclusions or alternative tools are mentioned, leaving usage largely implied.

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 provide idempotent, non-negative, and non-read-only hints. The description adds that the tool returns a stability verdict and observation count, but it does not disclose potential side effects (consistent with readOnlyHint=false) or explain how the verdict should be interpreted.

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 two concise sentences, front-loaded with the primary action and quickly stating the return value. Every sentence adds value with no redundancy or fluff.

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 there is no output schema, the description should more thoroughly explain the 'stability verdict' format and how the observation count is to be used. It provides a high-level return but leaves the agent without enough detail to confidently interpret the results.

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 input schema already describes all parameters with 100% coverage. The description does not add parameter-specific details; it only mentions the high-level concept of checking against a blueprint pattern, which helps but is not essential 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 clearly states the tool's purpose with a specific verb ('Check') and resource ('recent submissions vs established pattern for this Blueprint'). It distinguishes itself from sibling tools like check_blueprint_health by focusing on drift detection rather than overall health.

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 implies a clear use case (monitoring whether submissions still match a blueprint's pattern), but it does not explicitly mention when to prefer this tool over alternatives or provide exclusions. Sibling tools with overlapping functionality are not referenced.

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 adds the key behavioral trait that the tool returns 'status=skipped' without a realization block, and labels itself as diagnostics-tier. However, the annotations provide no safety hints (all false), and the description does not disclose whether this tool mutates state, requires special permissions, or what the output structure looks like. It carries only part of the burden.

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 two sentences, front-loaded with the main purpose, and includes all necessary scope and alternative guidance without extraneous text. Every clause provides 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?

For a diagnostics tool with no output schema and all-false annotations, the description adequately covers the tool's purpose, triggering condition, and relationship to alternatives. It omits details about the response format or side effects, but the core selection and invocation context is complete enough for an agent to act.

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% with descriptions for each parameter, so the baseline is 3. The description adds meaningful context by explaining that a 'realization' block is required within the payload, which clarifies the expected structure for the 'structured_data' parameter beyond the schema's generic 'extracted fields' description.

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 states the tool performs 'Structural realization analysis of a payload against the Blueprint's reference configuration', which is a specific verb-resource combination. It also distinguishes itself from siblings by mentioning 'Diagnostics-tier tool' and directing standard checks to 'validate or analyze_anomaly'.

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 guidance is provided: 'prefer validate or analyze_anomaly for standard checks' names specific alternative tools. The prerequisite requirement ('requires a realization block; otherwise status=skipped') also clarifies when this tool is appropriate versus when it will not produce useful results.

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 read-only, idempotent, and non-destructive behavior. The description additionally explains the comparison semantics (content_hash vs semantic_hash) and the possible verdicts, providing behavioral insight beyond the annotations without contradicting them.

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 concise and well-structured, starting with the core action, then explaining the hash distinction, and ending with possible verdicts. Every sentence adds value without redundancy.

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 tool's complexity and lack of an output schema, the description covers the essential behavior and result space. It explains the dual-hash approach and lists all verdicts, making the tool's behavior understandable. It could theoretically detail return structure, but the core context is sufficiently complete.

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% for the three parameters, so the baseline is 3. The description adds conceptual context about how payload_a and payload_b are compared, but does not provide additional syntax or constraint 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?

The description clearly states the tool's function with a specific verb ('Compare') and resource ('two payloads'), and it distinguishes itself via the dual-hash design and explicit verdicts. This is more specific than sibling tools like validate or analyze_anomaly, making its purpose unambiguous.

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 implies usage whenever semantic equivalence of payloads is needed, and it provides clear context about the hash mechanisms. It does not explicitly mention alternatives or exclusion scenarios, but the context is sufficient to guide appropriate use.

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 tool executes a comparison run and evaluates future state validity, which is useful context but not extensive. It does not contradict annotations and adds moderate value beyond the structured 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?

The description is exactly two sentences, front-loaded with the core action, and includes a clarifying hyphenated summary. Every word earns its place; there is no filler or repetition.

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 moderate complexity (5 parameters with 100% schema coverage, no output schema), the description sufficiently explains the tool's behavior and use case. It could benefit from a note on what the comparison output looks like, but the combination of schema and annotations fills most gaps. A 4 reflects that it's nearly complete but missing some behavioral detail.

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%, meaning every parameter has a description in the schema. The tool description itself does not add parameter-specific detail, so it does not go beyond the schema. Baseline 3 is appropriate given the high coverage.

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 states the verb ('Run') and the resource ('the same data under two rule sets'), and explains the purpose: comparing which future states remain valid. This is a precise what-if analysis for rule changes, which distinguishes it from sibling tools like compare_semantic_equivalence or check_drift.

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 provides clear context: use this tool when you need to perform what-if analysis on rule changes by running data under two rule sets. It does not explicitly enumerate alternatives or exclusions, but the scenario is well-defined enough to guide an agent. A 4 is appropriate for clear context without explicit 'when not to use' 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 indicate a write operation (readOnlyHint=false). The description adds valuable behavioral context by stating it 'Returns the new Blueprint's API key,' and explains the Blueprint is the governance contract validation runs against. No contradiction with annotations; minor lack of detail about failure modes is acceptable given 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 three sentences, front-loaded with the core verb+resource, and each sentence adds value: the definition, guidance on alternatives, and the return value. No wasted words or redundant repetition of schema details.

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 complex 16-parameter tool with no output schema, the description provides a strong mental model, usage alternatives, and the key return value. The schema covers individual parameters, so the description does not need to enumerate them. It could mention the observe/enforce mode more prominently, but that is already well-described in 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 description coverage is 100%, so the baseline is 3. The description mentions 'blueprint_guide' for rule/constraint types, which mirrors schema descriptions but adds no additional parameter syntax or format beyond what the schema already provides.

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 begins with 'Create a Blueprint - the governance contract validation runs against,' providing a specific verb and resource while immediately defining the Blueprint's role. It further clarifies what the Blueprint defines (fields, math, ranges), which distinguishes it from sibling tools like update_blueprint or delete_blueprint.

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 explicitly states when not to use this tool: 'Start from load_rule_pack or discover_patterns if you have no rules yet,' and points to the blueprint_guide prompt for full reference. This gives clear alternatives and conditions, satisfying the dimension fully.

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 only include false hints; the description adds substantial behavioral detail: stages validate in order, repairs propagate forward, TTL bounds the run, and it returns chain_id. These are meaningful traits not captured elsewhere.

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: first states the core action and behavior, second differentiates siblings, third states return value. Zero 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?

For a 4-param tool with no output schema, the description covers core semantics, ordering, repair behavior, TTL, return value, and sibling relationships. It leaves some edge cases (prerequisites, failure modes) but remains remarkably complete for its complexity.

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 parameter (api_key, blueprint, stages, ttl) already has clear documentation. The description's mention of TTL bounds the run reinforces ttl's schema but adds no new syntax or format. It earns baseline score only.

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 ('Create') and resource ('multi-agent sequential chain'), then details its key behavioral properties (ordered validation, repair propagation, TTL bound). It also names sibling tools ('submit_chain_stage', 'handoff_audit') with their distinct roles, making the tool's purpose unambiguous.

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 identifies two sibling tools and their functions, telling the agent when to use them instead of this one: submit_chain_stage advances the chain, handoff_audit verifies transitions. This provides direct alternative 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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the 'Diagnostics-tier tool' label and explains the input requirement (known-correct version), which provides context beyond annotations. It does not fully describe output behavior or error cases, but the annotation coverage lowers the burden.

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 three sentences, front-loaded with the core purpose, and every sentence adds value: the first explains what it does, the second gives usage guidance and a sibling alternative, and the third sets expectations via 'Diagnostics-tier tool.' No filler or redundancy.

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 no output schema, the description does disclose the expected output categories (rule violations, boundary violations, systemic structural error, per-field contributions). It also provides usage context and a diagnostic tier label. While it doesn't detail the exact output shape or all edge cases, the combination of annotations and schema makes it sufficiently complete for a diagnostic 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 parameters are already well-documented in the schema. The description references 'original and corrected values' and 'per-field contributions' but adds no new semantic detail beyond what the schema's property descriptions already provide. Baseline 3 is appropriate.

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 opens with a specific verb ('Split') and clearly states the resource and action: decomposing errors between original and corrected values into distinct categories (direct rule violations, boundary violations, systemic structural error). It also differentiates itself from the sibling tool analyze_anomaly, making the purpose unmistakable.

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 explicitly states when to use this tool ('Use with a known-correct version to diff against') and names the alternative tool for a different scenario ('use analyze_anomaly when you only have the suspicious payload'). This is an ideal when-to-use/alternative formulation.

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 destructiveHint annotation, the description warns that agents using the deleted key will receive auth errors immediately, and clarifies that the associated Blueprint is NOT affected. This gives critical operational context about consequences and side effects that annotations alone 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?

Every sentence earns its place: purpose stated first, then destructive warning, then alternative tool, then parameter specification. The formatting with dashes and line breaks makes it scannable with no redundancy or fluff.

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 tool with three parameters and no output schema, the description covers the purpose, side effects, alternative tool, and parameter disambiguation. The confirm parameter is already fully described in the schema, so its absence in the description is acceptable. This is a complete and self-sufficient description.

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 adds significant meaning beyond the schema by explaining that 'key_to_delete' can be either the full 'gai_' string or a key_id (SHA-256 hash from list_api_keys). This is not evident from the schema field description 'The gai_ key to delete' and directly aids correct parameter usage.

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 opens with 'Permanently delete one of the caller's API keys', using a specific verb and resource that clearly states the action and scope. It distinguishes itself from the sibling tool delete_blueprint by noting that deleting a Blueprint with its keys is a separate operation.

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 provides when-to-use and when-not-to-use guidance: to delete just a credential, use this tool; to delete a Blueprint and all its keys, use delete_blueprint. It also clarifies the two acceptable forms for specifying the target key (full key string or key_id from list_api_keys), leaving no ambiguity.

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 discloses irreversibility ('Irreversible'), the confirmation requirement ('requires confirm=true'), and the side effect of revoking the blueprint's API keys. These details go beyond the annotations, which only indicate destructive and idempotent hints, adding valuable behavioral 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 description is three concise sentences, front-loaded with the primary action. No wasted words; each sentence adds necessary context.

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 delete operation with full schema coverage and no output schema, the description covers the key aspects: what is deleted, the irreversibility, the confirmation requirement, and the scope relative to account-level keys. No critical 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?

The input schema already provides descriptions for all 3 parameters (100% coverage), including confirm's 'Must be true to confirm this irreversible action'. The tool description adds no new parameter semantics beyond reiterating the confirm requirement, so it stays at the baseline.

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 states the action: 'Permanently delete a Blueprint and revoke its API keys.' This distinguishes it from sibling tools like delete_api_key and update_blueprint, and notes account-level keys are unaffected, clarifying scope.

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 does not explicitly name alternatives, but the note 'Account-level keys are unaffected' implies that account-level key deletion should use delete_api_key. It also states the requirement 'requires confirm=true', providing a clear 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?

The description adds meaningful behavioral context beyond the all-false annotations: it is deterministic, requires no Blueprint, and explicitly states 'Source data is not stored.' This provides privacy and operational guarantees that annotations don't convey. However, it doesn't mention side effects or whether any state persists.

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 two well-structured sentences. The first sentence front-loads the purpose and key constraints (deterministic, no Blueprint), and the second adds the workflow (approve_rule) and data privacy. No waste or redundancy.

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 no output schema, the description communicates the expected result ('candidate validation rules and structural document types') and adds critical context like determinism, data retention, and the next step. It could explicitly mention return format, but it is reasonably complete for a discovery 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 baseline is 3. The description adds minor value by clarifying that blueprint is optional ('no Blueprint required') despite the schema's default, and by equating 'documents' to 'records.' No additional parameter details are provided.

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 states the tool learns candidate validation rules and structural document types from a batch of records. It uses a specific verb ('learn') with explicit resource and differentiates itself by noting 'no Blueprint required' and referencing approve_rule as a follow-up, distinguishing it from sibling tools.

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 intended use is implied through the purpose ('Learn candidate validation rules...'), but there is no explicit when-to-use or exclusions. It mentions 'Promote results with approve_rule' as a workflow hint, but doesn't clarify when to choose this over alternatives like validate or structural_types.

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. The description adds meaningful behavioral context beyond this: it is deterministic, operates from the current data state, and produces ranked valid next states under Blueprint rules. This aligns with annotations and adds useful detail without contradiction.

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, well-structured sentence. It front-loads the core concept ('Deterministic forward reasoning') and then explains the behavior concisely, with no wasted words or redundant repetition of schema details.

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 no output schema, the description does not explicitly state the return format, but it does indicate the output will be ranked valid next states. Combined with the fully documented parameters, this is sufficient for an agent to invoke the tool and interpret the general result, though it could be richer regarding output structure.

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%, with each parameter already well-documented. The description ties structured_data to 'current data state' and blueprint to 'Blueprint's rules,' but it does not add parameter-specific meaning beyond what the schema provides. Baseline 3 is appropriate.

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 phrase ('generate and rank') and clearly identifies the resource ('valid next states reachable under the Blueprint's rules'). It distinguishes forecasting from siblings like counterfactual or check_drift by emphasizing deterministic forward reasoning from the current data state.

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 implies usage for deterministic forward exploration of reachable states, but it does not explicitly state when to prefer this tool over alternatives, nor does it mention exclusions or prerequisites. It provides context but no explicit when/when-not 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, idempotentHint, and destructiveHint. The description adds context that this is a post-hoc digest, meaning it does not perform fresh analysis, and that it produces a recommendation. This extra context about the tool's behavior goes beyond the annotations, though it does not disclose error handling or edge cases.

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 two sentences, with the primary purpose in the first sentence and usage guidance in the second. Every word earns its place, and it is front-loaded with the core functionality.

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 having no output schema, the description clearly states the return value (confidence level with a recommendation) and the input requirement (state_vector from validate or get_execution_trace). Given the tool's simplicity and strong annotations, this is complete and unambiguous.

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%, with both api_key and state_vector having descriptive schema text. The tool description adds no further parameter-level details, 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?

The description uses a specific verb ('Summarize') and a precise resource ('an already-computed state_vector') and states the output (a confidence level high/medium/low with a recommendation). It also differentiates from siblings by explicitly mentioning analyze_anomaly and check_drift as alternatives, establishing a clear post-hoc role.

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 explicitly says when to use this tool ('Post-hoc digest') and when not to ('use analyze_anomaly or check_drift for fresh analysis of raw data'). Naming the alternative tools provides clear guidance for selection.

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 cover safety (idempotentHint true, destructiveHint false, readOnlyHint false). The description adds behavioral context beyond annotations by specifying the exact return payload (per-node trace with timing, deterministic flags, verdict, hash) and clarifying it is a validation run, which is useful for understanding side effects and output. No contradictions.

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 concise: two sentences. The first sentence front-loads the primary function and output contents, while the second provides usage guidance. Every sentence earns its place without redundancy.

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?

There is no output schema, so the description carries the burden of explaining what is returned. It lists the key components (trace, verdict, hash). It also gives clear usage context. It does not detail edge cases, cost, or error behavior, but for a debugging tool with well-covered schema, this is sufficiently complete.

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%, with all parameters (api_key, blueprint, structured_data) already having descriptions. The tool description does not add parameter-specific details beyond what the schema provides, so the baseline of 3 is appropriate.

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 states the tool's purpose: 'Run validation and return the per-node execution trace' with specifics (node names, deterministic flags, timing, verdict, determinism hash). It distinguishes itself from the sibling 'validate' tool by explicitly noting 'this is for debugging and audit preparation'.

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 usage guidance is given: 'Use validate for normal operation; this is for debugging and audit preparation.' This tells the agent when to choose this tool over the primary validation tool, satisfying both when-to-use and alternative identification.

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, indicating safe read behavior. The description adds useful context about durability ('durable audit trail') and completeness ('every recorded decision and its reasons'), which goes beyond the annotations without contradicting them.

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 concise, front-loaded with the verb, and every phrase adds value. It efficiently communicates the tool's purpose and the nature of the returned data without any 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?

For a simple read-only retrieval tool with two well-documented parameters and no output schema, the description provides sufficient context: it defines the audit trail, its scope ('governed generation'), and its content ('every recorded decision and its reasons'). This gives the agent a complete picture of what to expect.

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 description adds no additional parameter-level semantics. The parameter descriptions in the schema already document the API key format and the inference_id purpose, so the tool description is not required to compensate.

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 the specific verb 'Retrieve' with a clear resource: 'the durable audit trail for a governed generation' and specifies the content ('every recorded decision and its reasons'). This clearly distinguishes it from sibling tools like get_execution_trace or recent_inference_decisions.

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 implies when to use the tool (when needing an audit trail of decisions and reasons) but does not explicitly contrast it with alternatives or state when not to use it. There is no mention of sibling tools or exclusionary context.

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?

With all annotations false, the description carries the full burden. It discloses that decisions are 'durably recorded' and that an action with explanation is returned. However, it does not clarify whether the tool actively modifies or stops the generation or merely returns a recommendation for the caller to act on. The side-effect profile beyond recording is ambiguous.

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 sentences, front-loaded with purpose and timing, then return values and persistence. Every sentence earns its place with zero 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?

The tool has 7 parameters, nested objects, and no output schema. The description covers purpose, timing, return values, and persistence, which is sufficient for basic invocation. It does not detail the explanation format or error behavior, but given the tight prose, it is largely complete.

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 every parameter has a description. The tool description adds no parameter-specific meaning beyond the schema, so the baseline of 3 applies. It does not clarify how parameters like payload map to the listed actions, but the schema already covers syntax.

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 states the tool's function: 'Quality-govern an in-progress AI generation step BEFORE its output is used.' It uses a specific verb and resource, and distinguishes from the sibling tool validate by contrasting in-progress vs finished documents. The list of returned actions (STOP, CONTINUE, etc.) further clarifies the scope.

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 explicitly mentions that it 'complements validate, which checks finished documents,' giving a clear when-to-use criterion. It also points to get_inference_trace for later retrieval, implying a usage flow. However, it does not enumerate other alternative tools like repair or reject_rule, so it lacks explicit exclusions.

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 and other safety traits, and the description adds meaningful behavioral context: it explains that the tool checks a context capsule of verified facts and produces a compatibility verdict if proposed_data is supplied. This goes beyond what annotations provide, though it doesn't cover all edge cases.

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 two sentences, front-loaded with the primary action, and includes relevant sibling names without excess. Every sentence contributes 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?

Given annotations cover safety and schema covers parameters, the description is fairly complete. It explains the tool's purpose and the role of proposed_data. However, there is no output schema, and the description does not mention what the audit returns or error conditions, leaving a slight 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 100%, so parameters are already well-documented. The description adds a bit of context for proposed_data (checking mutations), but does not significantly elaborate on other parameters. Baseline of 3 is appropriate.

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 states the verb 'Audit' and the resource 'handoff between two chain stages', with specific detail about verifying facts and catching field mutations. It also names sibling tools, distinguishing itself from related operations.

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 provides clear context for when to use this tool—when auditing a handoff between stages—and mentions sibling tools as related. However, it does not explicitly state when not to use it or provide a direct comparison to alternatives beyond naming them.

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 and idempotentHint, so the description does not need to restate safety. It adds valuable context about masking and the inclusion of Blueprint bindings, which goes beyond the structured 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 that is front-loaded with the action and resource. Every word contributes meaning without redundancy.

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 is a straightforward list operation with strong annotations and a single well-described parameter. The description fully covers the user's need to know what the tool does and its key behavioral nuance (masking).

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 input schema has 100% coverage with a clear description for the only parameter (api_key). The tool description adds no new parameter-level detail, but the schema is sufficient, so baseline 3 is appropriate.

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 the specific verb 'List' plus the resource ('this account's API keys') and adds useful detail ('masked' and 'their Blueprint bindings'). This clearly differentiates it from siblings like delete_api_key and rotate_api_key.

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 'this account's' provides clear context that it is scoped to the authenticated account, implying a read-only listing. It does not explicitly name alternatives or exclusions, but the purpose is self-evident.

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 as true/false appropriately, so the safety profile is covered. The description adds value by disclosing the response contents (counts per field/rule/constraint, mode, and a workflow_name field), which is especially important because there is no output 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 sentences, each purposeful: the first states the action and returned details, the second provides a concrete downstream use. Zero 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?

For a simple list operation with rich annotations and a one-parameter schema, the description covers the account scope, the returned summary fields, and how to use the result (workflow_name for validate). No output schema exists, but the description fills in key return-value details.

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 single parameter api_key is fully documented in the schema with type and description ('GeodesicAI API key (gai_...)'), so the description adds no parameter-level meaning. With 100% schema coverage, 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?

The description opens with the specific verb 'List' and identifies the resource as 'Blueprints on this account,' then adds distinguishing detail: 'with field/rule/constraint counts and mode.' This clearly separates it from sibling create/update/delete/health tools.

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 provides an explicit downstream usage instruction: 'Use the returned workflow_name as "blueprint" in validate.' This gives clear context for when to call list_blueprints (before validation), though it does not explicitly contrast with alternative inspection tools like check_blueprint_health.

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 mark the tool as read-only and idempotent. The description adds behavioral nuance beyond those annotations: loading a template, the list-when-omitted behavior for pack_id, and the follow-up workflow with create_blueprint. It does not detail the return format, but the safety profile is well-covered by 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?

Three short, purposeful sentences. The first sentence states the core purpose, the second gives usage instructions, and the third provides workflow context. No filler or redundancy.

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 simple two-parameter shape and strong annotations, the description covers the essential usage context: what the tool loads, how to list packs, and what to do next. The lack of an output schema is not a major issue because the description focuses on the action and workflow rather than return values.

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 parameters are already documented. The description adds meaningful semantics for pack_id by stating that omitting it lists available packs, which directly clarifies the parameter's conditional behavior. The api_key parameter is adequately covered by 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 uses a specific verb ('Load') with a concrete resource ('prebuilt Blueprint template') and lists example domains (invoices, timecards, legal, POs, claims). It clearly distinguishes the tool's role from create_blueprint by describing the next step in the workflow.

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 guidance is provided: 'Call without pack_id to list packs' and then 'create_blueprint to save a customized copy.' This communicates both when to use the tool and how it relates to an alternative/successor tool.

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. The description adds context about the behavior (sweeping bounds and reporting stability metrics) without contradicting the annotations. It clarifies the analytical, non-mutating nature of the operation and lists what is reported.

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 two sentences, front-loaded with the action verb 'Sweep', and every phrase adds value. The output components are listed cleanly, and the usage instruction is a separate concise sentence.

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 no output schema, so the description carries the burden of explaining return values. It lists the three key outputs (stable band, flip scales, advice) and gives a clear use case. While it could elaborate on what 'verdict stability' means, the essential context is present for a read-only analysis tool with good annotations.

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 schema already documents all parameters (config, api_key, blueprint). The description adds minimal parameter-specific meaning beyond the schema, but it does tie 'blueprint' to 'numeric constraint bounds'. Per the rubric, a baseline of 3 is appropriate when schema coverage is high.

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 ('Sweep') and clearly identifies the resource ('the Blueprint's numeric constraint bounds') and the outputs ('verdict stability', 'stable band', 'scales where the verdict first flips', 'advice'). This clearly differentiates it from sibling tools like check_blueprint_health or validate.

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 provides a clear usage context: 'Use before deploying bound changes.' This tells when to use the tool, though it does not mention when not to use it or name alternatives. It gives a specific trigger scenario, which is more than a vague implication.

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, establishing safety. The description adds the scope ('across all runs') and the categories of decisions, but does not disclose ordering, pagination behavior, or how filters interact with the list. With annotations covering safety, this is acceptable but not rich.

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 line plus a clarifying fragment, with no redundancy. It is front-loaded with the main purpose and scoped clearly. 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 read-only listing tool with full parameter schema coverage and safety annotations, the description is adequate but not complete. It does not describe the output format or any edge cases (e.g., empty results), and there is no output schema to compensate.

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 parameters (limit, action, api_key) are self-explanatory from their schema descriptions. The tool description does not add any parameter-specific meaning, 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?

The description clearly states the tool returns recent generation-governance decisions across all runs, with specific decision types (approved, held, escalated). It effectively distinguishes from governance actions like govern_inference or approve_rule, though it lacks an explicit verb like 'list' or 'fetch'.

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 provides no guidance on when to use this tool versus alternatives. It does not mention exclusions or contextual use cases, such as 'use this to review past decisions' vs 'use govern_inference to make a new decision'. The 'across all runs' scope is useful but does not constitute usage 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 cover read-only (false), destructive (false), and idempotent (true). The description adds that the operation prevents promotion into a Blueprint and that it's a follow-up to discover_patterns, enriching the behavioral context without contradicting 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?

Two sentences with front-loaded action, then consequence and workflow linkage. No redundant words.

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-required-param action with good schema and annotations, the description provides sufficient context: purpose, effect, and workflow position. It could mention reversibility or return value, but overall it's adequate.

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?

All three parameters have descriptive schema text (100% coverage). The description does not add new parameter meaning beyond the schema, but it's consistent and clarifies the origin of rule_id ('from discover_patterns'), which is already in the schema. 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?

The description uses a specific verb ('Reject') with a clear resource ('discovered candidate rule') and outcome ('will not be promoted into a Blueprint'). It explicitly references approve_rule and discover_patterns, distinguishing it from sibling tools.

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 provides workflow context: 'Pair with approve_rule after discover_patterns' indicates the tool is used in sequence after discovery and as the counterpoint to approval. Though not exhaustive, it clearly situates the tool relative to alternatives.

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 declare the tool read-only, idempotent, and non-destructive. The description adds that it returns corrected values and is one-shot, which clarifies the output behavior and invocation model beyond what annotations state. This is more than the minimal bar, so a 4 is warranted.

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 extremely concise: two sentences that front-load the core action ('One-shot repair') and immediately provide a key alternative. No wasted words; every sentence 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?

Given the tool has no output schema but the description explains the return value (corrected values), and the schema fully documents all parameters, the description is complete enough for an agent to select and invoke it correctly. It does not cover edge cases like already-valid data, but that is not essential for basic invocation.

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 input schema covers all five parameters with 100% description coverage, so the schema already provides the necessary parameter semantics. The description does not add parameter information, but it does not need to; the baseline of 3 is appropriate.

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 identifies the tool as a one-shot repair that returns corrected values for failing data under the Blueprint. It uses a specific verb and resource, and explicitly distinguishes itself from the sibling tool repair_path by contrasting the one-shot output with step-by-step guidance.

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 provides explicit guidance on when to use this tool versus repair_path: use repair for the corrected values directly, and use repair_path to see the steps. This satisfies the when-to-use and when-not-to-use criteria, even though it does not mention all other siblings.

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 discloses that this tool returns an ordered path of intermediate states rather than a single final state, and that it can be used to compare alternative repairs. Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds the path-oriented behavior and the distinction from repair.

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 two sentences: the first states the core function, the second immediately distinguishes it from the sibling tool. Every phrase earns its place with zero wasted words.

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 description covers the core purpose, usage context, and output type (ordered path), and the schema handles parameter details. However, because there is no output schema, the description could clarify the structure of the path (e.g., fields, step format) and the meaning of ranking criteria like 'drift' or 'risk' beyond enums. Still, given annotations and clear differentiation, it's reasonably complete.

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 schema provides descriptions for all 5 parameters, covering 100% of them, so the description doesn't need to elaborate. The description implies the tool operates on 'field changes' and 'invalid data', which aligns with the structured_data parameter, but doesn't add syntax or format details beyond the schema. Baseline 3 is appropriate.

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 ('Find') and resource ('sequence of field changes') and clarifies it produces an ordered path of intermediate states. It explicitly distinguishes from the sibling tool 'repair' by name, making its purpose unambiguous.

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 usage guidance: it says to use repair_path to explain or audit the fix, or compare alternative repairs, and contrasts it with repair, which provides a one-shot nearest fix. This clearly frames when this tool is preferred over the alternative.

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 destructiveHint=true and readOnlyHint=false, but the description adds valuable context: the old key stops working immediately and the new key inherits bindings. This goes beyond the annotation and helps the agent anticipate consequences. It doesn't cover auth requirements or rate limits, but for this tool the disclosed behaviors are sufficient.

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 sentences, front-loaded with the core action, no filler. Each clause contributes: replacement, immediate invalidation, binding inheritance. This is a model of concise, well-structured tool documentation.

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 is simple (2 params, no output schema) and the description covers the main behavior and consequences. However, it does not state what the response contains—specifically, whether and how the new key is returned. Since the new key is essential for use, this omission creates a meaningful gap. Without an output schema, the description should have mentioned the return value.

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%: both parameters have clear descriptions (api_key is the GeodesicAI API key, key_to_rotate is the target key). The description repeats the effect on key_to_rotate but does not add new meaning beyond the schema. This matches the baseline score of 3 for high schema coverage.

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 the specific verb 'Replace' with the resource 'API key', clearly distinguishing this rotation tool from sibling tools like delete_api_key and list_api_keys. It also states the outcome (fresh one, old stops working, new inherits bindings), leaving no ambiguity about the tool's function.

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 clearly implies when to use this tool (when you want to replace a key while preserving bindings), but it does not explicitly mention when not to use it or name alternative tools. For example, it does not say 'If you want to permanently delete a key, use delete_api_key instead.' This is a gap, so it stops short of full 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 read-only and idempotent, and the description adds concrete behavioral context: the no_session return status and namespace scoping. It clarifies what happens when prerequisites are not met, which is value 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 two sentences, front-loaded with the verb and resource, and every phrase adds information. No filler or repetition of schema details.

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 no output schema, the description names the return content (counts, distinguishing fields, domain hints) and failure mode (no_session). It is adequate for a read-only tool with only two parameters, though it could be slightly richer on response format.

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% for both parameters (api_key and blueprint) with descriptive titles, so the baseline is 3. The description does not add additional parameter-specific meaning beyond what the schema provides.

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 ('Retrieve') and clearly identifies the resource: 'document categories a discover_patterns session identified', with details on what is returned (counts, distinguishing fields, domain hints). This distinguishes it from sibling tools like discover_patterns itself.

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 implies it should be used after discover_patterns has run, and explicitly notes the no_session status if it hasn't, giving context for when the tool is applicable. No alternatives are named, but the reference to a discover_patterns session provides clear usage context.

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 are all false, so the description carries the burden of disclosing behavior. It adds that the platform validates the submission and advances the chain, and that responses include next-stage info and accumulated repairs. This goes beyond the annotations by explaining the lifecycle and response contents, though it does not cover failure modes.

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 two sentences, front-loaded with the core action, and every word adds value. It efficiently covers the action, the validation/advancement behavior, and the response contents 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?

Given the tool's moderate complexity (4 required params, no output schema), the description is sufficiently complete. It covers the response contents, which is essential without an output schema, and integrates with the chain workflow. Some limitations (e.g., failure behavior) are not mentioned, but the description is otherwise adequate.

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 does not add much beyond the schema; structured_data is briefly referenced, but the schema already provides full descriptions for all four parameters.

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 states the verb 'Submit' with a specific resource ('data for the chain's current stage') and explains the outcome (validation and advancement). This distinguishes it from siblings like create_chain and validate by focusing on the chain-stage progression context.

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 implies a clear use case: when you have a chain and need to submit data for its current stage. It does not explicitly name alternatives or exclusions, but the context ('platform validates it and advances the chain') makes the purpose and timing evident.

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 annotations (idempotentHint, non-destructive), the description reveals partial update semantics ('Only passed fields change'), list clearing syntax ('pass [] to clear a list'), immutability of workflow_name, and that existing API keys are unaffected. These are behavioral details not present in the schema or 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?

Three sentences, each carrying distinct information. The first states the core operation, the second conveys mutation semantics and constraints, and the third differentiates from create_blueprint. No filler or redundancy.

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 16 parameters and no output schema, but the description covers the essential operational contract: what updates, how partial updates behave, how to clear lists, what cannot change, and side effects on API keys. It omits error cases and return format, but for an update operation with the annotations provided, this is sufficient to invoke 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?

The schema covers 100% of parameters, but the description augments meaning with global update semantics: only passed fields change and [] clears lists. This is especially helpful for array-typed parameters like derived_fields and semantic_checks, though it doesn't map each parameter individually.

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 opens with 'Update an existing Blueprint in place' – a specific verb and resource. It explicitly contrasts with create_blueprint by stating it modifies an existing Blueprint and mints no new key, distinguishing it from the closest sibling.

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 names create_blueprint as the alternative and explains the functional difference: 'modifies an existing Blueprint, mints no new key.' It also sets clear expectations by noting workflow_name cannot be renamed and existing API keys keep working, offering both when-to-use and limitation context.

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 discloses detailed return content (findings, repair suggestions, determinism hash, re-verifiable certificate) and emphasizes deterministic behavior ('Same input + same rules = same verdict'), which adds value beyond the idempotentHint annotation. 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?

Three concise sentences that are front-loaded with the core purpose, followed by output details and a determinism note. Every sentence contributes value with no redundancy.

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 description compensates for the lack of an output schema by enumerating all return elements. Combined with complete parameter schema coverage, it provides enough context for an agent to select and invoke the tool 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?

The schema already provides descriptions for all three parameters with 100% coverage. The description does not add new parameter-level details beyond reinforcing the relationship between structured_data and Blueprint rules, so it meets the baseline but doesn't exceed 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?

The description clearly states the tool validates structured data against a Blueprint's rules, specifies the timing ('BEFORE the result is used'), and lists concrete output types (PASS, FAIL, REVIEW). This distinguishes it from sibling tools like verify_certificate or validate_repair.

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 'BEFORE the result is used' provides clear temporal context for when to use this tool. However, it does not explicitly mention alternatives or when not to use it, so it falls short of full explicit 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?

The description discloses key behavioral traits: it returns repair suggestions as corrected values with associated rules, provides PASS/FAIL/REVIEW verdicts with reasons and proof, and performs validation plus repair suggestion in a single call. It complements the annotations by clarifying that it only suggests repairs, not actually applies them. No contradiction with annotations found.

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 two sentences with no filler. The first sentence states the core functionality and the repair-suggestion behavior, and the second clarifies output verdicts. It is efficiently front-loaded and every sentence 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?

The description covers the core behavior, output verdicts, and the combined validation+repair nature of the tool. Given the absence of an output schema, it does a good job explaining return values. It could benefit from explicit guidance on choosing this tool over the separate validate/repair siblings, but it is otherwise complete.

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%, with all three parameters described in detail (e.g., api_key format, blueprint default, structured_data keys open). The description adds no additional parameter-specific semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.

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 states the tool validates structured data against a Blueprint and, on failure, provides repair suggestions (corrected values with rules) in the same call. It explicitly references 'validate' for comparison, distinguishing this combined validation+repair functionality from the basic validate tool.

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 implies usage when the user wants both validation and repair suggestions in one call, and mentions 'Same verdicts as validate' to align with validation expectations. However, it does not explicitly state when to prefer this over the separate 'validate' or 'repair' sibling tools, so guidance is clear but not fully 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 declare readOnly, idempotent, and non-destructive behavior. The description adds useful context about the hash chain check and full recomputation, but does not disclose what the response looks like or any potential failure modes.

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 two short, impactful sentences. It front-loads the action and uses a memorable phrase ('trust nothing, recheck everything') without wasted words.

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 four parameters and no output schema, yet the description covers the core operational modes well. However, it omits any mention of return values, error conditions, or prerequisites for full mode (e.g., data matching the original), leaving some gaps for an agent to infer.

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 schema provides complete descriptions for all four parameters, including the optional nature of 'data' for integrity mode and 'derivation_rules'. The description reinforces the role of 'data' in full mode but does not add significant new meaning 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 clearly states the tool re-verifies a validation certificate, and distinguishes two operating modes (integrity and full). However, it does not explicitly differentiate from sibling tools like verify_replay or validate, which would make it 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 description explains when to use each mode (integrity vs full) and implies that full mode requires the original data. It does not explicitly state when to prefer this tool over alternatives such as verify_replay, leaving some ambiguity for the agent.

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, and non-destructive behavior. The description adds valuable behavioral context about determinism (byte-identical results) and what mismatch fields indicate (data, rules, platform version, or trace), which goes beyond the minimal safety hints and helps the agent anticipate outcomes.

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 three sentences, front-loaded with the core purpose, followed by behavioral detail and a clear use case. Every sentence earns its place with no fluff or repetition of schema fields.

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 is moderately complex with nested objects and no output schema. The description explains what the tool does, what it proves, and how to interpret mismatches, but it does not describe the exact return format. Given the absence of an output schema, a bit more return detail would be helpful, but the description remains largely complete for decision-making.

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 parameters themselves are already documented. The description adds high-level meaning by tying contracts to 'same input + same rules' and mentioning possible mismatch causes, but it does not enrich individual parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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 starts with a specific verb 'Verify' and names the resource 'two replay contracts' with a clear outcome: 'same input + same rules = same result, byte-identical.' It also distinguishes itself from siblings by focusing on deterministic execution equivalence and mismatch localization, making its purpose unambiguous.

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 provides explicit use cases: 'prove a past decision reproduces today or that a migration changed nothing.' It does not explicitly state when not to use it or name alternative tools, but the context is clear enough to guide appropriate selection among the sibling tools.

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