Reality Graph Verification Tools

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description adds value by stating that no hidden assumptions are applied and the output is purely arithmetic with a concrete balancing action. This provides additional transparency beyond 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, well-structured sentence that packs essential information: the purpose, what it outputs, and a key transparency claim. No unnecessary words. It is front-loaded with the purpose and efficiently communicates its value.

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 states the tool 'calculate' metrics and provides some output behavior ('shows the arithmetic and a concrete balancing action'). However, it does not explain the return format or structure, which is important given there is no output schema. The input complexity (6 parameters) and lack of output schema suggest the description should cover more about result format to be 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 only 17% (only the 'lang' parameter has a description). The tool description does not provide any additional details about the parameters or their semantics. It merely lists the metrics calculated but doesn't clarify each input. This fails to compensate for the low coverage, leaving the agent without sufficient guidance on parameter meaning.

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

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

The description clearly states the tool's purpose: 'Calculate weekly review demand, utilization, capacity gap, supported change throughput, and changes lacking evidence.' It uses a specific verb ('calculate') and resource ('verification capacity'). The sibling tools are all different (e.g., check_release_readiness, plan_change_verification), so this tool is well-distinguished.

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 context: 'No cost model, benchmark, or hidden industry assumption is applied; the output shows the arithmetic and a concrete balancing action.' This helps the agent understand what the tool does and does not do, implying when to use it (for raw arithmetic capacity calculation). However, it does not explicitly state when not to use it or name alternatives, so it's slightly less than perfect.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context: the verdict is based only on supplied evidence and the tool does not inspect code/CI/deployment, which further clarifies its safe, read-only nature. This goes beyond what annotations provide.

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 output (verdicts), then immediately clarifies scope. No unnecessary words. Every sentence adds value.

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 explains the tool's purpose and limitations but does not explain how the verdict is determined (e.g., thresholds for GO/NO_GO) or detail all required inputs. With 12 required parameters and no output schema, more information about the decision logic would be beneficial.

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 low (38%). The description mentions 'acceptance-criterion results, check evidence, rollback, monitoring, limitations, and independent review' which maps to some parameters but does not detail each of the 13 parameters. It provides a high-level mapping but insufficient detail for an agent to understand all inputs.

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

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

The description clearly states the tool returns one of three verdicts (GO, CONDITIONAL, NO_GO) based on supplied evidence, and explicitly distinguishes itself from tools that inspect code/CI/deployment. This differentiates it from sibling tools like search or fetch.

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

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

The description states the tool is for use when acceptance-criterion results, check evidence, rollback, monitoring, limitations, and independent review are available. It explicitly says what it does NOT do (inspect code, CI, deployment), providing clear when-not-to-use guidance. However, it does not mention alternative sibling tools for those cases.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: it promises 'the full calculation path, labeled assumptions, thresholds, and sources' and explicitly disclaims benchmark claims. It also notes language behavior ('Set lang='de' for a German report'). No contradictions with annotations.

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

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

The description is two sentences and front-loaded with purpose. The first sentence covers what, the second covers usage and additional parameters. It is concise given the tool's complexity (16 params, 4 metrics). A slight length is justified, but it remains efficient and well-structured.

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

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

For a tool with 16 parameters and no output schema, the description provides a complete picture: it lists the four computed metrics, the annual cost estimate, the availability of a full calculation path, assumptions, thresholds, sources, and the optional German report. This is sufficient for an agent to invoke the tool correctly and understand 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?

Input schema covers 100% of parameters with descriptions, so baseline is 3. The description adds extra semantics by explaining which parameters enable which metrics ('enables the unverified-merge rate', 'enables the GVR and review-depth metrics') and that only team_size is required. This goes beyond the schema's per-field 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 identifies the tool's purpose: 'Estimate a software team's verification debt from team parameters. Computes the four published metrics...' It specifies the exact output (metrics and annual cost estimate), uses a specific verb ('estimate'), and distinguishes itself from siblings like calculate_verification_capacity by focusing on debt estimation rather than capacity.

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

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

The description explains when to use the tool: 'Only team_size is required; every additional parameter refines the estimate.' It also clarifies scope with 'Deterministic arithmetic from published models - no benchmark claims.' However, it does not explicitly compare against alternatives or state when not to use it, so a brief exclusion would improve clarity.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds what the tool returns (summary, definitions, key facts, FAQ, sources, canonical URL), providing context beyond the safety profile.

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. Front-loaded with purpose and key details. Every sentence adds value.

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 output schema present, description doesn't need to detail return structure, but it still lists key fields returned. Input is fully described. Complete for a simple fetch 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 coverage is 100% and the description's parameter explanation mirrors the schema's description exactly. No additional meaning 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?

Clearly states the verb 'Fetch', the resource 'document from the Reality Graph knowledge base', and the input methods (by id or URL). Distinguishes from sibling 'search' which returns search results, not a single document.

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?

Specifies two valid input formats (id or URL). Does not explicitly mention when not to use or alternatives, but the sibling list provides context. Clear enough for basic usage.

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

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

The description reinforces annotations: 'Static content, nothing stored' aligns with readOnlyHint=true and destructiveHint=false. It also details the template structure, format options, and language support, providing full behavioral transparency beyond the annotations.

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

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

The description is a single paragraph with front-loaded purpose, followed by key details. Every sentence contributes value—no redundancy. It efficiently covers the template structure, usage context, format options, and static nature.

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 no output schema, the description comprehensively explains the template contents, including filled example and guidance. It covers all significant aspects: format variants, language support, and static behavior. This is sufficient for the tool's purpose.

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 coverage and enum descriptions for both parameters, the schema already provides clear definitions. The description adds meaningful context: format='json' returns machine-fillable JSON, default is markdown; lang='de' sets German. This adds 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 clearly states it returns a template for a verifiable task contract, explicitly listing its sections (goal, non-goals, etc.). It distinguishes itself from sibling tools like validate_task_contract by explaining the usage sequence: write the contract before running an AI agent, and verify after.

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 clear usage context: 'Write the contract before an AI agent runs; verify the result against it after.' It implies alternatives (e.g., validate_task_contract for verification) but does not explicitly name other siblings or state when not to use this 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 and destructiveHint=false. Description adds that content is static and nothing is stored, confirming safety and no side effects. This adds context beyond the annotations.

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

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

The description is a single dense sentence but contains all essential information. It is front-loaded with the main purpose. Could be slightly more structured but remains efficient and clear.

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 details the template contents and behavior. It covers format options, language, and confirms static nature. The tool is simple with 0 required params, and the description is sufficiently complete.

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

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

Schema coverage is 100% with enum descriptions. The description enriches parameters: explains format='json' for machine-fillable vs default markdown, and lang='de' for German. This adds value beyond the raw schema.

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

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

The description clearly states the tool returns a verification report template, explains its contents (task recap, files changed/touched, validation results, etc.), and distinguishes it from sibling tools like get_task_contract_template. The verb 'Returns' and resource 'template for verification report' are specific.

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 indicates when to use it ('right after an AI-assisted run') and explains format options ('json' for machine-fillable, default markdown). It does not explicitly state when not to use it or compare to siblings, but the context is clear enough.

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 (readOnlyHint=true), the description clarifies it does not use LLM, stores nothing, and returns a status table with evidence and questions. This fully discloses behavioral traits.

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

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

Four sentences: purpose, methodology, output, language option. Front-loaded with the key action, no redundant words, and each sentence adds necessary 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 tool with two parameters and no output schema, the description covers purpose, method, output format, and limitations (no LLM, no storage), making it self-contained.

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?

Both parameters have schema descriptions (100% coverage), but the description adds a usage hint for lang ('Set lang='de' for a German report'), providing extra guidance beyond the enum.

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: checking if a free-text work order for an AI coding agent is verifiable, using heuristic linting against four building blocks. This distinguishes it from sibling tools like validate_task_contract which likely perform deeper verification.

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 use before handing over a task to an AI agent, and notes it checks form not content. However, it doesn't explicitly exclude cases or compare with siblings like calculate_verification_capacity, leaving some 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?

Annotations (readOnlyHint=true, destructiveHint=false) already indicate non-destructive read-only behavior. The description adds valuable behavioral context: it never invents a confidence score and does not inspect code, providing clarity beyond what annotations 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?

The description is two concise sentences, front-loaded with the main output categories. Every sentence adds distinct value without redundancy.

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

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

Despite no output schema, the description enumerates all expected outputs (risk tier, checks, scenarios, etc.) and explicitly states what it does not produce. Given the parameter count and constraints, this is fully informative for an AI 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 description coverage is 100%, with detailed enum descriptions and constraints for all parameters. The tool description adds overall context but no additional per-parameter meaning, 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 clearly identifies the tool as transforming change characteristics into specific outputs (risk tier, checks, etc.) and explicitly distinguishes itself from siblings by noting it does not inspect code and is used before implementation/review.

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 'Use before implementation or review' and clarifies what the tool does not do (inspect code, invent confidence score). While it doesn't directly compare to sibling tools, the context signals provide sibling names, and the guidance is clear enough for correct invocation.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds context on the corpus scope (40+ glossary definitions, 700+ FAQ answers) and return fields (title, URL, snippet), enhancing transparency beyond 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 concise with two sentences. The first sentence provides a dense, clear overview of the search scope and content, while the second sentence clarifies the output and directs to fetch. No 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?

Given the presence of annotations, input schema, and output schema (not shown), the description is fairly complete. It covers the search domain, return format, and links to fetch, though it might optionally mention result limits or ranking.

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 description adds minimal parameter meaning. It mentions support for English and German, aligning with the lang enum, but does not elaborate further on parameter behavior.

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 it is a full-text search over the Reality Graph knowledge base, listing specific content types and topics. It distinguishes itself from the 'fetch' sibling tool by explicitly mentioning its use to read a result.

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 to 'Use fetch to read a result,' indicating when to use this search tool versus a sibling. It implies the search is for retrieving snippets, but does not explicitly state when not to use it.

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

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

Annotations indicate read-only and non-destructive behavior. The description adds valuable context: deterministic validation, no LLM involvement, no storage, and detailed checks (vague words, missing markers). 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 at ~100 words, front-loaded with key verb 'Validates', and each sentence provides essential information 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?

Despite having no output schema, the description fully covers return values (verdict, scores, fixes). With simple parameters and high schema coverage, the description is complete and enables correct 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%, so baseline 3. Description adds meaning: contract must be filled JSON from get_task_contract_template, and explains lang enum values ('de' for German), improving parameter understanding.

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

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

The description clearly states the tool validates a filled task contract for completeness, decidability, and other checks, listing specific validation dimensions and outputs. It distinguishes itself from siblings by noting it validates form, not correctness, and uses no LLM or storage.

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

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

The description explains when to use this tool (after filling a task contract template) and what it does not do (no LLM, no storage, validates form only). It lacks explicit when-not-to-use alternatives but context is sufficient.

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