Reality Graph Verification Tools

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

Annotations declare readOnlyHint=true, and the description adds significant behavioral context: 'Deterministic arithmetic from published models — no benchmark claims,' and mentions the full calculation path, labeled assumptions, thresholds, and sources. This goes well 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 concise and well-structured. It starts with the main action, lists outputs, clarifies determinism, and ends with usage guidance. Every sentence adds value, with 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 no output schema, the description explains what the output includes (metrics and cost estimate) and the nature (full calculation path, assumptions). It does not specify the exact format (e.g., JSON vs. textual report), but the mention of a 'report' and language option implies a readable format, which may be sufficient.

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 well-documented in the schema. The description adds overarching context ('every additional parameter refines the estimate') and the lang parameter hint, but no further semantic enrichment for individual 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 tool's purpose: 'Estimate a software team's verification debt from team parameters.' It lists the four metrics computed and the annual cost estimate, distinguishing it from siblings like 'get_verification_report_template' which likely provide templates rather than computation.

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 that only team_size is required and additional parameters refine the estimate, guiding usage. It also mentions setting lang='de' for a German report. However, it does not explicitly contrast with alternatives or state when not to use the 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, destructiveHint=false. Description adds value by detailing the returned content (summary, definitions, key facts, FAQ, sources, canonical URL).

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 wasted words, front-loaded with verb and resource.

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?

Output schema exists for return values; description explains what is returned. Complete for a retrieval tool with good annotations and single parameter.

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 covers 100% of parameter, but description adds example of id format ('/verification-debt') and clarifies that full URL is also accepted, adding meaning beyond 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?

Clearly states 'Fetch a document from the Reality Graph knowledge base by id or by full URL' with example format, distinguishing it from search and other siblings.

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?

Implies usage after search (by id as returned by search) but does not explicitly state when not to use or provide 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?

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds that content is static and nothing is stored, aligning with annotations and providing extra context about the tool's non-destructive, read-only behavior.

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, three sentences, no redundant information. It front-loads the main purpose and each sentence contributes useful information without waste.

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 (goal, non-goals, boundaries, etc.) and mentions version (v0). It is sufficiently complete for a template retrieval tool with clear 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 coverage is 100% with parameter descriptions for lang and format. The description adds value by explaining the effect of each parameter (e.g., 'format='json' returns a machine-fillable JSON structure; default is a compact markdown skeleton') and using them in context.

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 fill-in template for a verifiable task contract, listing its contents (goal, non-goals, etc.) and distinguishing it from sibling tools like validate_task_contract. It uses specific verbs and resources.

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?

Provides clear usage guidance: 'Write the contract before an AI agent runs; verify the result against it after.' It explains format and language options, though it does not explicitly exclude alternative tools.

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, destructiveHint=false. Description adds 'Static content, nothing stored' reinforcing safe behavior, and explains format options. 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?

Three sentences front-load purpose, then detail. Every sentence adds value: purpose, contents, format, language. No redundancy.

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

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

For a simple static template retrieval with 2 params and no output schema, description fully explains what is returned, usage context, and parameter options. No gaps.

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

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

Schema provides enum values with basic descriptions. Description adds meaning: 'format='json' for a machine-fillable structure; default is a compact markdown file' and 'lang='de' for German', enriching 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?

Clearly states 'Returns the free fill-in template (v0) for a verification report' with specific contents. Distinguishes from sibling tool 'get_task_contract_template' which is for contracts.

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?

Describes usage context ('right after an AI-assisted run') and template content, but does not explicitly state when not to use or mention alternative tools like 'check_verification_debt'.

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

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

Annotations already indicate readOnlyHint=true, and the description adds value by disclosing that the tool is deterministic, uses no LLM, and stores nothing. This goes beyond the annotations, providing full transparency about behavior and side effects.

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

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

The description is a single paragraph of about 100 words, front-loading the core purpose. Each sentence adds essential information: the function, what it checks, what it returns, and key qualifiers (no LLM, nothing stored). 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?

The tool has no output schema, but the description explicitly details the return value: 'a status table with evidence, the concrete questions that close each gap, and a fill-in skeleton.' This compensates well. The sibling tools are related but distinct, and the description leaves no major gaps for a lint operation.

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% description coverage, setting a baseline of 3. The description adds extra meaning by specifying that 'task' is the work order for an AI agent and that setting 'lang=\'en\'' or 'lang=\'de\'' controls the report language. This provides helpful context beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Check whether a free-text work order for an AI coding agent is verifiable BEFORE handing it over.' It uses specific verbs ('Check') and resources ('task specification'), and distinguishes itself from sibling tools by emphasizing form-checking vs. content validation or debt checking.

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 says to use the tool 'BEFORE handing [the task] over' to an AI agent, providing clear context. It also notes what it checks (form, not content) and that it's deterministic with no LLM, implicitly excluding scenarios requiring content verification. However, it does not explicitly name alternatives or conditions to avoid using 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?

Discloses return format (documents with title, URL, snippet) beyond annotations (readOnlyHint, destructiveHint). No contradictions with annotations. Adds useful 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?

Two focused sentences. First sentence states purpose and scope, second provides usage hint. No wasted words; effectively 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?

Given high schema coverage and presence of an output schema, the description fully covers purpose, behavior, and return format. No gaps for an agent to operate.

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 detailed descriptions for both parameters. The description adds the language context ('English and German') but does not significantly enhance semantic understanding beyond schema defaults.

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 explicitly states 'Full-text search over the Reality Graph knowledge base' and lists specific content (40+ glossary definitions, 700+ FAQ answers), clearly distinguishing it from sibling tools like fetch and check_verification_debt.

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?

Provides explicit guidance to 'Use fetch to read a result', indicating post-search action. However, it does not explicitly state when not to use search or mention alternatives beyond fetch.

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?

Disclosures beyond annotations: deterministic, no LLM, nothing stored. Also describes return values (verdict, scores, fix). No contradictions with readOnlyHint=true.

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?

Single paragraph with all key information, but could be slightly more structured for quick scanning. Still concise and no 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?

Describes return values despite no output schema, covers all aspects of tool behavior. No missing context.

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 covers 100% of params but description adds meaning: contract must be from get_task_contract_template and format='json', lang 'de' for German. Adds value beyond 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?

Clearly states it validates a filled task contract, specifies what it checks (goal/non-goals, acceptance criteria, etc.), and distinguishes from siblings like lint_task_spec which is separate.

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

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

Explicitly says it validates a FILLED contract, mentions it validates form and completeness not correctness, but does not explicitly state when to use vs alternatives or scenarios to avoid.

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