Datagov Uk

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds cost implication (Anthropic requires user's API key) and that default model is free. Does not contradict 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?

Four sentences, front-loaded with action, no wasted words. Each sentence adds necessary detail (purpose, default, API key usage, use cases). 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?

Covers essential information for a probe tool with 4 parameters and no output schema: describes return format (per-model scores + combined view). Missing error handling for missing API key or invalid models, but overall complete for intended use.

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 has 100% coverage for all 4 parameters. Description adds value by explaining the relationship between _apiKey and models ('only needed if 'anthropic' is in models') and that default model is free. Clarifies semantics 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?

Description clearly states the tool probes LLMs to score visibility (0-100) for a given entity. It specifies default model (Workers AI), optional Anthropic with API key, and return structure. Differentiates from siblings like 'scan_competitor_ai_presence' by focusing on AI knowledge scoring.

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 contexts: AI-marketing audits, pre-launch brand checks, competitive monitoring. Mentions default model and BYO key for Anthropic. Does not explicitly state when not to use or compare to alternatives, but context is sufficient for typical use.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds behavioral context: the tool routes to the right tool among 3,300, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. This provides useful extra insight 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 informative but slightly lengthy (~4 sentences). It is well-structured with key guidance front-loaded and examples listed, earning a slight deduction for verbosity but still effective.

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 purpose, usage guidelines, and parameter meaning (implicitly). It lacks explicit return format details, but mentions structured answer with citations. Given the tool's complexity and lack of output schema, it is mostly 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 aliases documented. The description does not add additional semantics beyond what the schema already provides for the 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 it routes questions to 3,300 tools across 737 verified sources for authoritative structured data, and explicitly differentiates from web search. It lists specific domains (SEC filings, FDA drug data, etc.) and example questions, making the purpose very 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 explicitly says 'PREFER OVER WEB SEARCH' and provides extensive examples of when to use (e.g., 'what is', 'look up', 'find', 'get the latest') and what types of questions. It also mentions using even if web search could answer, giving clear usage priority over 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?

Annotations (readOnlyHint, openWorldHint, idempotentHint) are fully consistent with description. Description adds extensive behavioral details: fan-out examples, resolver contract, parent event extractor, news fallback handling, safety mechanisms (low-confidence short-circuit, closed market suppression). 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?

Description is lengthy but every sentence adds value. Front-loads purpose and input formats. Contains detailed examples and edge cases. Could be slightly more structured (e.g., bullet points for sections), but remains effective and informative.

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?

No output schema provided, but description compensates fully with detailed field breakdowns (result.market, result.analysis, result.evidence, resolver fields, parent_event, news fields). Covers all states (low-confidence, closed, illiquid). Complete for a complex research 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% with descriptions for all three parameters. Description adds significant context: market parameter accepts slug, URL, or question text; depth parameter provides quick/thorough with default; include_raw explains response size trade-offs. Exceeds schema-only 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?

Description clearly states the tool researches Polymarket bets by pulling Pipeworx data. It specifies input formats (slug, URL, question text) and output (evidence packet + comparison). Distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage through unique behavior.

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 use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). Gives detailed behavior for closed markets, low-confidence matches, and wide spreads, including when to inspect resolver fields. No ambiguity about when to use versus 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds significant context: data sources (SEC EDGAR/XBRL, FAERS), fixes (post-Run-6 fix for fiscal year handling), and output details (paired data, citation URIs, sorting by primary metric). This goes 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?

Single paragraph, front-loaded with purpose and usage. Slightly long but every sentence adds value (purpose, guidelines, data details, alternative value). Could be tightened but effective.

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 complexity (two data sources, two parameters, no output schema), description covers purpose, usage, behavior, and parameters well. Provides return information (paired data, citation URIs, sorting). Missing error handling details but overall sufficient for a comparison 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 has 100% coverage with descriptions, but description adds deeper meaning: explains what each type enum does in detail, provides examples for values (e.g., 'AAPL, MSFT' for company, 'ozempic, mounjaro' for drug), and clarifies format (tickers/CIKs vs names). Adds significant 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?

The description clearly states 'Compare 2-5 companies (or drugs) side by side in one call' and lists specific query patterns ('compare X and Y', 'X vs Y', 'which is bigger'). It distinguishes the two entity types with different data sources (SEC EDGAR vs FAERS). This is a specific verb+resource that differentiates from sibling tools like entity_profile.

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 use cases ('Use for ...') and explains it replaces 8-15 sequential lookups. However, no explicit when-not-to-use or alternatives beyond the replacement hint. Still clear context for when to invoke.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that resources are downloadable files, not queryable datastore tables, which provides useful behavioral context beyond annotations 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 two sentences, front-loads the core functionality (full dataset record by id/slug), and each sentence adds value: the first defines the tool, the second clarifies resource structure and behavior. No redundancy.

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

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

The description explains that the return includes resources with specific fields (url, format, name). It references CKAN package_show, which implies standard dataset metadata, and since there is no output schema, this is reasonably complete for a simple retrieval tool, though it could explicitly list top-level fields.

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

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

The input schema already describes the 'id' parameter as a UUID or slug with an example. The description repeats this but adds no extra semantics for the parameter. With 100% schema coverage, a score of 3 is 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 tool returns the full dataset record by id or slug, referencing CKAN package_show. It specifies that it includes resources, each with url, format, and name, distinguishing it from search tools like search_datasets.

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

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

The description implies usage when you have a specific identifier (id or slug) for a dataset. However, it does not explicitly state when not to use it or suggest alternatives (e.g., search_datasets for queries without an ID), so it is clear but lacks 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?

The description reveals that the tool returns 'full input schemas (with curated examples)' and that results are 'ready to call directly, no second schema lookup needed.' This goes beyond the annotations (which already indicate read-only, idempotent, non-destructive) by detailing the output format and the streamlined workflow.

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 moderately concise, starting with the core purpose ('Find tools by describing the data or task') and then providing a list of example domains. It could be slightly shorter, but every sentence adds value. It is well-structured with a clear call to action at the end.

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 complexity of a meta-tool that discovers other tools, the description is comprehensive. It explains the use case, when to call, the domain coverage, and the output structure (tools with names, descriptions, schemas, examples). Without an output schema, the description fully compensates by detailing what the agent will receive.

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, with detailed descriptions for each parameter (e.g., 'Natural language description of what you want to do'). The description adds no new parameter meaning beyond the schema, so it meets the baseline but does not elevate it. The mention of 'curated examples' in the output is not directly parameter-related.

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 and resource: 'Find tools by describing the data or task.' It also lists specific domains (SEC filings, financials, etc.) and explains the output (top-N most relevant tools with names, descriptions, and full schemas). This distinguishes it from sibling tools, which perform specific actions rather than discovery.

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 instructs: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context for when to use the tool. It does not explicitly mention when not to use it or list alternatives, but the guidance is strong enough for an agent to decide.

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 significant behavioral context beyond the annotations, detailing data sources (SEC EDGAR, XBRL, USPTO, GLEIF), return fields with specific caveats (e.g., patents sunset, fundamentals fix), and idempotent/read-only nature. There is no contradiction with annotations.

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

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

The description is comprehensive and front-loaded with purpose and usage, but it is somewhat lengthy with inline details. It could benefit from structured bullet points for the return fields, but remains readable and free of fluff.

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

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

Given the lack of an output schema, the description thoroughly explains each return field and its nuances (e.g., five filings max, fundamentals freshness, patent soft-fail). It also addresses the parameter limitation (names not supported). For a complex tool aggregating multiple sources, this is highly 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 clear descriptions, but the description adds value by clarifying that 'value' accepts only ticker or CIK (not names), and that 'type' is currently limited to 'company'. This goes beyond the basic schema, though the schema already details the enum and string format.

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 retrieves comprehensive data about a US public company in one call, distinguishing it from siblings by noting it replaces calling 10+ individual tools. The verb 'Get everything' and the specific resource 'US public company' make the purpose precise.

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 scenarios are given: when a user asks 'tell me about X', 'research Acme', etc., or when 10+ tools would otherwise be called. It also provides a clear exclusion: names are not supported, and directs the agent to use 'resolve_entity first' instead. This provides strong when-to-use and 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 destructiveHint=true and readOnlyHint=false. The description confirms deletion but adds no further behavioral context (e.g., irreversibility, permissions, side effects). With annotations present, the bar is lower, but the description does not significantly enhance transparency beyond them.

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

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

The description consists of two concise sentences. The first sentence states the action, and the second provides usage guidance. No unnecessary 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 tool's simplicity (one parameter, no output schema) and good annotations, the description covers purpose and usage adequately. It could mention irreversibility, but given low complexity, it is mostly 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 input schema has 100% coverage with description 'Memory key to delete' for the only parameter 'key'. The description adds no additional meaning beyond what the schema provides, 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 explicitly states 'Delete a previously stored memory by key,' clearly identifying the verb (delete) and resource (stored memory). This distinguishes it from sibling tools like 'remember' and 'recall.'

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 when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' It also advises pairing with 'remember' and 'recall', offering clear 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, idempotentHint=true, and destructiveHint=false. The description adds that it fetches the page and extracts title/description/key links, which is useful context 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?

Three sentences with clear structure: purpose and outcome, process, use cases. No redundant 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 the tool has 2 parameters, no output schema, and annotations cover safety, the description adequately explains the process, output format, and use cases. It is complete for a simple 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%, so the schema already defines both parameters. The description adds no additional meaning beyond what the schema provides, meeting the baseline of 3.

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: generating an llms.txt file for AI crawlers. It specifies the action, resource, and context, distinguishing it from sibling tools like scan_competitor_ai_presence.

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 lists three use cases: indexing a client's site, drafting for own project, or auditing competitor's AI visibility. While it does not directly state when not to use it, the use cases provide clear 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, openWorldHint, idempotentHint, and destructiveHint. The description adds context about the source (data.gov.uk) and types of organizations, but does not disclose additional behavioral traits 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 two sentences, front-loaded with the main function, and then provides 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?

For a simple list tool with one parameter and no output schema, the description is complete: it explains what is listed, where from, and how to use the results (filtering in search_datasets).

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% for the single parameter 'limit', which already includes a description. The tool description adds no additional semantic value for the parameter 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 clearly states it lists publishing organizations on data.gov.uk, using specific verb 'List' and resource 'organizations'. It also mentions the CKAN API and distinguishes from siblings like 'organization_details' and 'search_datasets'.

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 guidance on how to use the output (use returned org name in search_datasets), but does not explicitly state when not to use this tool or mention alternatives like 'organization_details'.

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 no additional behavioral traits (e.g., rate limits, auth needs, data freshness), so it adds minimal value 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 with no wasted words. The purpose is front-loaded and the use case is succinctly stated.

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 provides enough context for a simple retrieval tool, listing key return fields (display name, description, dataset count) despite no output schema. No additional info is needed for typical use.

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 well-documented. The description mentions the optional dataset sample corresponding to 'include_datasets', but adds no further nuance or usage details.

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 'Full details for one publishing organization' and lists specific fields (display name, description, dataset count). It distinguishes from siblings like 'list_organizations' (which lists all) and 'dataset_details' (which focuses on individual datasets).

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 a clear use case: 'Use to learn what a given UK publisher releases.' It implies a single-organization focus and contrasts with listing tools, though it lacks explicit exclusions or 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?

Discloses non-obvious behaviors: free, rate-limited to 5 per identifier per day, no tool-call quota impact, and that the team reads digests daily affecting roadmap. Annotations (readOnlyHint false, destructiveHint false) are consistent with a write-like operation that is not destructive.

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 yet thorough, with clear sentence structure. It front-loads the core purpose and then provides usage details. Slightly verbose but still efficient for the information conveyed.

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 feedback tool with no output schema, the description covers all necessary context: what to include, what to avoid, rate limits, quota impact, and how the feedback is used. It is fully adequate for an agent 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?

Schema coverage is 100%, baseline is 3. The description adds useful clarification: explains enum values for 'type', suggests message length and content, and notes 'context' is optional. This extra guidance raises the score above 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 starts with a clear verb-resource pair ('Tell the Pipeworx team') and specifies what kinds of issues to report. It is distinct from sibling tools which focus on data retrieval or analysis, 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?

Explicitly lists when to use (bug, feature/data_gap, praise) and what not to do (don't paste end-user prompt). Also notes rate limits and that it doesn't count against quota, providing complete 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 already declare readOnly, openWorld, idempotent, non-destructive. Description adds valuable context: data source (CF analytics-engine), no PII, cache durations (5min-1h). 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?

Single, well-structured paragraph with bullet-like list. Every sentence adds value, front-loaded with purpose and use cases.

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 1 param and no output schema, description explains return shape (pack, tool, count) and caching. Fully sufficient for agent 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 covers 100% with enum and description. Description adds semantic nuance: shorter windows show hot trends, longer windows steady-state demand. Provides guidance 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?

The description clearly states the tool returns top tools, top packs, and total call volume, with specific usage scenarios. It distinguishes itself from siblings like 'discover_tools' and 'ask_pipeworx' by focusing on real-time popularity data.

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 use cases (discovering hot sources, confirming canonical tools, alignment check) and explains window options. Lacks explicit when-not-to-use but contextually 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?

The description extensively discloses the tool's behavior: walking child markets, checking date-axis/threshold-axis ordering, computing partition_check, requiring Jaccard similarity ≥0.30, and filtering partitions with >20% placeholder fraction. This far exceeds the information in annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), providing crucial operational details.

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 well-structured with clear sections (TWO MODES, SEMANTIC ANCHOR, PARTITION FILTER, Response). However, it is somewhat verbose and could be trimmed by removing redundant technical details while retaining all 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?

Given the complexity of the tool (two modes, multiple checks, filtering logic) and the lack of an output schema, the description comprehensively explains all aspects: how each mode works, response structure (opportunities, partition_check), and conditions for valid signals. It leaves no significant gaps 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?

While the input schema already describes both parameters (event and topic), the description adds substantial meaning: it explains the two modes, provides concrete examples (e.g., 'when-will-bitcoin-hit-150k'), and clarifies the context and expected input format. This enables precise selection and invocation.

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: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies two distinct modes (event and topic), each with a clear verb and resource. This distinguishes it from sibling tools like polymarket_edges or polymarket_kalshi_spread.

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 each mode: 'event' for a single Polymarket event slug, and 'topic' for cross-event searches. It details conditions like Jaccard similarity and partition filters, but does not explicitly state when not to use the tool or suggest 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, openWorldHint, idempotentHint true, and destructiveHint false. The description adds significant behavioral context, such as caching (1h at KV level), the structure of the response (by_segment, fed_candidates/fed_note, _diagnostics), and the fact that Fed bets are excluded from ranking. There is no contradiction with annotations.

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

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

The description is detailed and front-loaded with the main purpose, but it is quite long. Every sentence provides relevant information, but some details (e.g., the exact model families and gates) could be more concise. It remains clear and well-organized.

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 thoroughly explains the return values: by_segment structure, edge fields (edge_pp_net, kelly_fraction, market data), and diagnostics. It also covers caching and the handling of Fed bets. The description is complete for understanding what the tool returns.

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. However, the description adds extensive meaning beyond the schema: it explains default values, trade-offs (e.g., slippage_pp gives context about polymarket fees), and the specific purpose of min_partition_leg_kelly. This adds significant value for 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 clearly states it scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It is specific about the resource (Polymarket markets) and the action (scanning and returning opportunities), and the context 'what should I bet on today' differentiates it from sibling tools like polymarket_arbitrage.

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 'Built for "what should I bet on today"' and mentions the purpose of discovering opportunities without paging hundreds of markets. It provides guidance on when to use the tool, but does not explicitly state when not to use it or mention alternatives among sibling tools. However, the parameters like min_liquidity and max_spread_pp give practical usage advice.

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 the tool is read-only, idempotent, and non-destructive. The description adds substantial behavioral context: it explains the spread calculation (Kalshi - Polymarket), details safety fields (compatibility_warning, temporal_alignment, skipped_cross_type), and clarifies when spreads are meaningless due to metric mismatches or temporal gaps. 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 comprehensive but somewhat lengthy. It front-loads the core purpose and then logically organizes modes, response fields, and safety checks. While informative, a slight restructuring (e.g., bullet points) could improve readability. Still, 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?

Given the tool's complexity (cross-venue spread, multiple modes, safety checks) and lack of output schema, the description is thorough. It explains the response structure, safety fields, and temporal alignment. An agent can fully understand how to invoke the tool and interpret results.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the interplay between parameters: topic as shortcut, and explicit tickers that override the topic-mapped side. It also provides examples in the schema. This justifies a 4.

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 core function: computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It uses specific verbs ('cross-venue spread', 'prices') and resources ('Kalshi and Polymarket'). It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on cross-venue comparison with Kalshi, not within Polymarket.

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 two usage modes (topic shortcuts and explicit tickers) and provides safety fields to determine when spreads are meaningful. It warns that pre-mapped topics are not always tradeable. However, it does not explicitly state when not to use the tool or recommend alternative tools among 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?

Adds context beyond annotations: scoped to user identifier, behavior when key is omitted (lists all keys). Annotations already indicate readOnly, idempotent, and non-destructive, which description aligns with.

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-loaded with core function, no redundant content. Every sentence provides 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?

Covers retrieval, listing, scoping, and tool pairing. No output schema, but return behavior is implied. Adequate for a simple key-value lookup.

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?

Parameter 'key' is documented in schema (description: 'Memory key to retrieve (omit to list all keys)'). Description reiterates the dual behavior but adds no new info beyond schema, which has 100% 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 a specific verb ('Retrieve'/'list') and identifies the resource ('value previously saved via remember'). It clearly distinguishes from sibling tools like 'remember' and 'forget'.

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?

States when to use: 'look up context the agent stored earlier... without re-deriving it from scratch'. Mentions pairing with remember/forget, but does not explicitly state when not to use or provide 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?

Adds significant context beyond annotations: parallel fan-out to SEC, GDELT/GNews fallback, USPTO soft-fail, return format, and window formats. No contradiction with readOnlyHint and others.

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, front-loaded with main purpose. Contains all necessary details without redundancy, though could be slightly more compact.

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 complexity (multiple sources, fallback, output schema missing), description fully covers behavior, parameters, return structure, and alternatives. Complete for agent decision-making.

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

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

Schema coverage is 100%, but description adds concrete examples for `since` (ISO date, relative shorthands like '7d', '30d') and clarifies `value` accepts ticker or CIK.

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 tool aggregates recent changes for a company, with specific examples like 'what's happening with X' and explicitly distinguishes from sibling entity_profile.

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 (updates, news, change-monitoring) and when not to use (static profile, for which entity_profile is recommended).

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 write operation (readOnlyHint=false) and idempotent hint. Description adds value by detailing persistence behavior: authenticated users get persistent memory, anonymous sessions retain for 24 hours. No 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?

Front-loaded with core purpose, then usage guidelines, then storage details. Every sentence adds value; 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?

For a simple 2-param tool with no output schema, description covers purpose, when/how to use, persistence details, and pairing with siblings. 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 100% with clear descriptions. Description adds usage context (examples of keys and values), enhancing 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?

Description clearly states verb ('Save') and resource ('data the agent will need to reuse'), with specific examples (ticker, address, preference). Distinguishes from siblings recall and forget explicitly.

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: 'when you discover something worth carrying forward'. Mentions paired tools recall and forget, but does not give explicit when-not-to-use 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?

Annotations already classify as readOnly/idempotent/openWorld. The description adds valuable context: it cascades through multiple endpoints internally, replaces 2-3 lookups, and provides output details (ticker, CIK, RxNorm ids, citations). 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?

Well-structured paragraph with bullet-point-like formatting for each type. Every sentence adds value, no fluff. Front-loaded with the core 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?

Despite lacking an output schema, the description fully explains return values for each type, including citation URIs. Given the tool's complexity (two entity types with distinct outputs), this is complete and sufficient for an agent to use 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 coverage is 100% with descriptions for both parameters. The description adds meaning beyond schema by explaining accepted input formats (ticker, CIK, name for company; brand/generic for drug) and auto-disambiguation 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 the tool resolves user-spoken names to canonical identifiers, specifies supported types (company, drug), and details what each returns. This is a specific verb+resource that distinguishes 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?

Explicitly says 'Use FIRST when you have a name but need an ID', providing clear context for when to invoke. Could be improved by stating when not to use (e.g., if IDs are already known) or mentioning alternatives, but still strong.

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 safe, read-only, idempotent behavior. The description adds valuable context: it calls ai_visibility_check internally, ranks results, and surfaces which entity is most/least recognized. 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?

Two sentences that front-load the main purpose and then add details. It is fairly concise but contains a bit of extra context that could be trimmed; however, it remains readable and effective.

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?

Without an output schema, the description correctly describes the return format (ranked list with score, confidence, signal density). It covers parameters and usage context well, though it omits error handling or constraints.

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 entities are treated as 'your brand + N competitors' and that the first entry is the subject for narrative.

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 compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and returns a ranked list. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic).

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 frames the use case as competitive AI-marketing audits with an example question. It implies when to use but does not explicitly state when not to, nor does it name alternatives, though sibling context provides differentiation.

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 declare read-only, open-world, idempotent. Description adds behavioral details: partial failures degrade gracefully, bundlephobia first measurement may take 5-30s, and sources_failed field behavior. 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?

Two sentences, highly informative, no wasted words. Front-loaded with composite nature and fan-out 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?

Covers ecosystem scope, return fields, failure modes, and latency. Without output schema, details are sufficient for an agent to understand behavior.

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%, but description adds value: clarifies package accepts scoped packages and version defaults to latest. Adds context 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?

Description clearly states the composite check for npm packages covering license, advisories, version history, and bundle size. It distinguishes from sibling tools by specifying ecosystem scope and linking to deps.dev:version for other ecosystems.

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 defines when to use: when an agent asks about safety, popularity, size, or cost of adding a package. Also notes alternatives for other ecosystems, providing clear usage boundaries.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds content language (English) and behavior of empty query, enhancing transparency beyond structured fields.

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

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

Two sentences, front-loaded with purpose, no superfluous 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?

Covers return fields, language, and pagination hints via parameters. Missing explicit explanation of sort/filter relationships, but overall adequate for a search 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%, baseline 3. Description adds value for 'query' (empty string browsing) but does not enrich other parameters 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?

Description clearly specifies verb 'search', resource 'data.gov.uk catalogue', and scope '57k+ UK government open datasets'. Returns fields are listed. No explicit differentiation from sibling 'dataset_details', but purpose is 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?

States when to use: searching across the catalogue. Suggests empty query for browsing. Lacks explicit 'when not to use' or alternative tools from sibling list, but context is provided.

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 the tool is read-only, open-world, idempotent, and non-destructive. The description adds value by detailing the return format (verdict, structured form, actual value, citation, percent delta) and explaining that it replaces multiple sequential calls. This provides behavioral insight 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 core purpose, gives usage guidance, specifies scope, and describes the return. 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?

Given the simplicity (1 parameter, no output schema, good annotations, and many siblings), the description is complete. It covers purpose, usage, scope, and output format, leaving no obvious gaps for the intended use case.

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 a single parameter and 100% schema description coverage, the baseline is 3. The schema already defines the parameter with an example. The tool description does not add significant additional semantics beyond what the schema provides, though it does reinforce the natural-language aspect.

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: fact-checking natural-language claims against authoritative sources. It provides specific examples and distinguishes it from siblings by focusing on factual verification, which is not covered by other tools in the list.

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 'Use when an agent needs to check whether something a user said is true' and gives example phrases. It also notes the tool's scope (company-financial claims) and what it returns. However, it does not explicitly state when not to use it or mention alternatives, which would strengthen the guidance.

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