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?

The annotations already declare readOnlyHint, idempotentHint, and a non-destructive profile, so the safety behavior is covered. The description adds the meaningful behavioral detail that no Blueprint is required)Skip, but it does not explain what kind of output is returned or how the anomaly explanation is presented.

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 sentences with no filler. The main purpose is front-loaded, and the optional blueprint caveat is placed at the end, making it easy to scan.

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

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

Given its simple explainer role and the strong safety annotations, the description is minimally viable. However, there is no output schema, and the description does not mention what the explanation looks like, how the 'usual pattern' is determined, or how the optional blueprint affects the analysis when one is supplied.

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 extra value by clarifying that structured_data is the record to analyze and that the blueprint is not a required prerequisite, beyond what the schema's default value implies. This helps an agent understand the relationship between the fields and the analysis.

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

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

The description states a clear verb ('Explain') and a specific resource: whether a record fits the usual pattern and which fields stand out. It conveys the tool's analytical purpose, though it does not explicitly name or distinguish it from related sibling tools like discover_patterns 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 offers only the prerequisite note 'No Blueprint required,' which hints at a usage condition but gives no guidance on when to choose this tool over alternatives. It does not state when to use analyze_anomaly versus sibling tools such as validate, discover_patterns, or geometric_confidence.

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 are all false, so they provide no safety or side-effect profile, forcing the description to carry the burden. The description does disclose that it returns a 'stability verdict and observation count' and implies a read-oriented check, but it does not explain side effects, whether any state is written, or what the verdict range/semantics are. No contradiction with annotations, but transparency is only partial.

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 that front-loads the primary purpose and immediately follows with the return value. Every phrase earns its place, and there is no redundant restatement of the tool name or schema.

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 should provide enough detail about return values and invocation context. It mentions a 'stability verdict and observation count' but leaves the verdict's form, possible values, and relationship to structured_data unclear. Given the large sibling set and all-false annotations, a bit more context would be needed for confident autonomous 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?

Schema coverage is 100%, with all three parameters described meaningfully. The description adds the conceptual context of 'recent submissions' and 'established pattern,' but does not clarify how these map to the structured_data parameter. The schema already handles parameter documentation, so the description's contribution here is minimal but not harmful.

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 a specific action ('check whether recent submissions still match the established pattern') and names the relevant resource ('this Blueprint'). It also indicates the output ('stability verdict and observation count'), giving enough specificity to distinguish it from many siblings, though it does not explicitly contrast it with related check tools like check_blueprint_health or check_realization.

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

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

The description gives no guidance on when to prefer this tool over alternatives, when not to use it, or what prerequisite context is needed. With many closely related sibling tools, the absence of any usage direction leaves the agent to infer suitability solely from the tool name and generic phrasing.

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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond those hints: it reveals the dual-hash normalization, that field renaming requires an explicit bijection, and that supplied rules make scalars and whitespace significant. This is valuable behavioral information about how the comparison operates rather than just a side-effect note.

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 only a few lines and ends quickly, but it includes a clear typographical stumble ('content_hash is content_hash normalizes') and a filler phrase 'content_hash is' that could be removed. It is compact, yet the redundancy and slightly awkward wording keep it from being fully polished.

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 the 8 parameters and absent output schema, the description never explains what the tool returns (a boolean, a hash, a diff, an object?), and it does not mention constraints_a/b at all. It also assumes the reader understands 'dual-hash design' without describing the return format. Since there is no output schema and some parameters, the description should bridge more of that gap, and fewer than 2 the task gets a 2.

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?

With 100% schema description coverage, the baseline is 3, but the description goes further by explaining the role of field_mapping ('renaming requires an explicit bijection') and rules_a/rules_b ('With supplied rules, scalar types and whitespace remain significant'). It does not say anything about constraints_a/b or payload_a/b beyond what the schema provides, but the added interpretation of key tricky parameters elevates it above 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 opens with a concrete verb and object ('Compare two payloads'), and frames the tool under a 'dual-hash design', making the main goal apparent. It also helps differentiate itself from structural comparison by ending with 'Structural similarity alone does not establish decision equivalence,' which positions it as a semantic instead of a syntactic check. The phrase 'dual-hash design' is jargon and the opening line stumbles with a repeat, keeping it from 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?

There is no direct statement of when to use this tool versus siblings such as structural_types or validate. However, the description implies usage through the emphasis on semantic marginals, field roles, and the line 'Structural similarity alone does not establish decision equivalence', which hints that semantic comparison is needed when decision equivalence matters. Because the guidance is implicit rather than explicit, it receives a 3.

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?

The annotations already declare read-only, idempotent, and non-destructive behavior, and the description is consistent with those traits. It adds the useful 'durable' qualifier and states that all recorded decisions with reasons are returned, but it does not disclose operational details such as empty-trace behavior, retention semantics, or ordering.

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 compact and front-loaded: the action is the first word, the resource follows immediately, and the content of the returned result is summarized in a brief subordinate clause. There is no filler or repeated 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 simple read-only retrieval tool with fully annotated parameters and no output schema, the description gives the agent the essential resource and the nature of the result. It is complete enough to form a correct call, and a fuller treatment would only need to add a small caveat about empty traces or return-shape expectations.

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% parameter description coverage, so the baseline is 3 even though the description itself defines no parameter specifics. The reference to a 'governed generation' and 'recorded decision/reasons' weakly relates to inference_id and blueprint_version, but it adds no semantic value 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 uses a specific verb ('Retrieve') and a specific resource ('durable audit trail for a governed generation') with a clear statement that the result includes every recorded decision and its reasons. It is clear in isolation, though it does not explicitly differentiate itself from get_execution_trace or recent_inference_decisions by name.

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

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

No guidance is given on when to use this tool versus related siblings such as get_execution_trace, recent_inference_decisions, or handoff_audit. The phrase 'for a governed generation' implies an audit context, but there are no explicit preconditions, alternative routes, or when-not-to-use conditions.

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 indicate readOnlyHint=false, so this is a mutating operation, yet the description does not contradict that. It adds valuable behavioral context such as the caveat that structural scores do not establish correctness, the need to check safe_to_finalize and acceptance coverage, and notes on persistence and tracing. This goes beyond the annotations, which are sparse.

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 dense and efficient, with each sentence adding new information. It front-loads the critical purpose and action list, then covers warnings and supplementary details. No redundant phrasing.

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 (8 parameters, nested objects, no output schema), the description covers the essential usage context, limitations, and operational details (persistence, tracing). It lacks explicit return-value structure, which the user must infer, but the enumerated actions partially fill that 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 coverage is 100%, so all parameters are documented in the schema. The description adds extra meaning by noting the payload depends on task_type and that constraints are optional governance controlsholistically. It also clarifies that inference_id groups steps, which the schema mentions but the description reinforces.

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: to quality-govern an in-progress AI generation step before output is used, and distinguishes it from a sibling tool (validate) that checks finished documents. It also lists the specific action results, making the tool's function 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 explicitly mentions when to use this tool ('BEFORE its output is used') and contrasts it with a sibling tool (validate), providing context for when it applies. However, it does not explicitly state when not to use it or mention alternatives beyond the one sibling.

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

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

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, so the safety profile is clear. The description adds useful scoping context ('this owner's Blueprint version', 'generation-governance decisions') but does not disclose ordering, pagination, or what fields the returned decisions contain. 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 with no filler and gets to the core subject quickly. However, it is a sentence fragment without an explicit operation, so the brevity comes at some cost to clarity.

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, and the description does not explain what a returned decision record looks like, how results are ordered, or how 'generation-governance decisions' relate to govern_inference. With five parameters and no output schema, the description leaves too much for the agent to infer about both selection and result interpretation.

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 even without parameter detail in the tool description. The description adds no parameter-level meaning beyond what the schema already provides; the mention of 'owner's Blueprint version' loosely aligns with the blueprint and blueprint_version parameters but adds little.

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 identifies the resource as 'recent generation-governance decisions' scoped to the owner's Blueprint version, so the agent can infer this is a read/list tool. It lacks an explicit verb like 'list' or 'returns', and it does not differentiate itself from sibling tools such as govern_inference or get_inference_trace.

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

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

There is no guidance on when to use this tool versus nearby siblings like govern_inference, get_inference_trace, or check_blueprint_health. The intended context is only implicit from the name and description, with no alternatives, prerequisites, or exclusions stated.

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

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

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?

All annotations are false, so the description carries the full burden. It discloses the return states (PASS, FAIL, REVIEW), the nature of findings, repair suggestions, the determinism hash, and the re-verifiable certificate. It also states the determinism guarantee explicitly, which is beyond the annotations and provides actionable behavioral insight.

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 verb and purpose, then enumerates outputs efficiently. Every clause adds information: timing, result set, determinism, and certificate. No fluff 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 there is no output schema, the description fully covers the return format: verdict (PASS/FAIL/REVIEW), findings, repair suggestions, hash, and certificate. It also explains the determinism property and the re-verifiability, which is crucial because sibling tools verify_certificate and verify_replay exist. For a validation tool of this complexity, nothing essential is missing.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description adds no new semantics about api_key, blueprint, or structured_data; it repeats the fact that Blueprint rules govern validation, which the schema already implies via the blueprint description. No additional value beyond the schema.

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

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

The description states a specific verb ('Validate'), a precise target ('structured data against a Blueprint's rules'), and the temporal condition ('BEFORE the result is used'). It also lists the return payload, distinguishing it from sibling tools like verify_certificate or check_blueprint_health, 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 description clearly implies when to use it ('BEFORE the result is used') and mentions the determinism and certificate aspects that relate to verify_certificate and verify_replay, but it does not explicitly name alternatives or state when not to use it. The context is provided but without formal 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 provide only basic hints (readOnly=false, idempotent=false, destructive=false), so the description carries the burden of behavioral disclosure. It clarifies that repair output is suggested values rather than applied changes, but it does not state whether the call has side effects, requires special authorization beyond api_key, or how the repair suggestions are generated. The phrase 'include repair suggestions... in the same call' is informative but not comprehensive.

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 earning its place. The primary action, the conditional repair behavior, and the compatibility with 'validate' verdicts are all front-loaded in a compact, readable way 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 no output schema, the description does a good job of indicating what the response will include (PASS/FAIL/REVIEW, reasons, proof, and repair suggestions). The main gap is that it doesn't explicitly clarify whether the operation is read-only or whether repair suggestions are always returned or only on FAIL, but the phrase 'when it fails' implies the latter. For a 3-parameter tool, this is nearly 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%, so baseline is 3. The description adds meaning beyond the schema by explaining the relationship between structured_data, Blueprint rules, and the repair suggestions (corrected values with the rule each fix is based on). This helps an agent understand how the parameters interact, which is more than simple schema restatement.

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

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

The description states a specific verb ('Validate'), the resource ('structured data against a Blueprint'), and the key distinguishing feature ('when it fails, include repair suggestions (corrected values with the rule each fix is based on) in the same call'). It also references the sibling 'validate' tool by saying 'Same verdicts as validate', making the scope and differentiation clear.

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 this tool is for cases where you want validation and repair suggestions in a single call rather than a separate validate-then-repair flow. However, it does not explicitly state when to prefer plain 'validate' or the standalone 'repair' sibling, leaving some routing to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: 'trust nothing, recheck everything' and the distinction between integrity-only and full recomputation. It doesn't mention rate limits or failure modes, but the core behavioral traits are disclosed 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?

Two sentences with zero waste. The first sentence states the core purpose, the second explains the two modes with a memorable imperative ('trust nothing, recheck everything'). Every word earns its place, 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?

For a read-only, idempotent verification tool with 100% schema coverage, the description is nearly complete. It explains the two modes and their data requirements. The only gap is that it doesn't describe the return value or what a successful verification looks like, but since there's no output schema and the tool is a verification action, the absence is minor. The description covers what an agent needs to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 5 parameters. The description adds value by explaining the semantic difference between integrity mode (omit data) and full mode (provide data), which maps directly to the 'data' parameter. It also clarifies that certificate comes from a prior validation response. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: independently re-verify a validation certificate. It distinguishes two modes (integrity mode and full mode) with specific behaviors, making it distinct from siblings like verify_replay or validate. The verb 're-verify' plus the resource 'validation certificate' is specific and 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 when to use each mode: integrity mode for hash chain checks, full mode for recomputing attested rules from scratch. It doesn't explicitly name alternatives or exclusions, but the mode distinction provides clear context for choosing between them. It could be improved by stating when to prefer this over verify_replay or validate, but the guidance is adequate.

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 carried by structured fields. The description adds value beyond that with the 'does not rerun the workflow or reconstruct historical reference populations' caveat, which prevents an agent from over-interpreting results as fresh executions or authoritative reconstructions. This is genuine behavioral context, though it omits authentication requirements or output behavior, which are minor given the annotation coverage.

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 three sentences, front-loaded with purpose and each sentence earns its place: scope, version/status context, and boundary caveats. No filler, no repetition of schema fields, no redundant elaboration. This is appropriately sized for the tool's complexity.

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 compares two nested replay_contract objects and has no output schema, so the description should compensate. It covers purpose and limitations well, but never states what the result looks like — a match score, a list of mismatches, or a boolean — nor what 'commitment integrity' means in terms of which components the comparison inspects. Given the deep nested parameters and the absence of an output schema, there are meaningful gaps an agent would face when interpreting the tool's result.

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 three parameters (api_key, contract_a, contract_b). The description contributes a slight addition by explaining that a 'match compares commitments,' which hints at the relationship between the two opaque nested contract objects. Yet it does not explain what a 'replay_contract' structurally contains or how the api_key is used, leaving the nested objects' semantics under-specified.

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

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

The description states a clear purpose: 'Check replay commitment integrity and compare recorded execution components.' This is a specific verb plus resource pair that is distinguishable from most siblings. However, it relies on the domain term 'commitment integrity' without defining it, and it does not explicitly name siblings like verify_certificate or compare_semantic_equivalence that it must be separated from. The scope is clear overall, but the relationship to the most similar siblings is left to inference.

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 useful exclusions: it does not rerun the workflow, reconstruct historical reference populations, or prove factual correctness. This tells an agent when NOT to rely on this tool (e.g., when it needs factual proof or a fresh execution). However, it never names the alternative tools for those cases, and the 'Version 4' note mostly addresses version history rather than routing the agent to the right sibling for the covered gaps.

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