Irail

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

Beyond annotations (readOnly, idempotent), the description adds critical behavioral details: default free model, BYO key for Anthropic, and return structure (score, confidence, signals, raw_response). 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?

Two concise sentences covering action, defaults, and optionality, followed by return format. No fluff, well 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?

Despite lack of output schema, the description thoroughly covers return fields. All parameters are explained with examples. Complete for the tool's complexity.

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

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

Schema coverage is 100%, baseline 3. The description adds value by explaining purpose of _apiKey, model defaults, and context usage examples, going beyond 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 probes LLMs for visibility scoring, using specific verbs and resources. It distinguishes from siblings like scan_competitor_ai_presence by focusing on LLM responses.

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 use cases (AI-marketing audits, brand checks) and explains when to provide _apiKey. However, it lacks explicit when-not-to-use or direct comparisons to similar sibling 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 provide readOnlyHint, openWorldHint, idempotentHint. Description adds context: routes to specific sources, returns structured data with stable pipeworx:// URIs, works on every tier, one fast call. 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?

Description is long but well-structured, starting with a preference statement, followed by use cases, examples, and sibling differentiation. Could be slightly more concise but earned its length.

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, but description compensates by detailing return format (structured answer with citations). Covers a wide range of factual questions and data sources, making it contextually complete for a query 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 multiple aliases for the question parameter. Description explains the parameter as 'Your question or request in natural language' and lists aliases, adding 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 it routes questions to thousands of sources and returns structured answers with citations. Distinguishes from siblings like ask_pipeworx_grounded and deep_research.

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 'PREFER OVER WEB SEARCH', provides examples of when to use, and when to step up to alternatives. Gives clear actionable guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: the source-preference ranking behavior, its experimental nature, and that it falls back to nothing (full working router). It does not contradict annotations and provides additional transparency.

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 front-loaded with 'Beta version of ask_pipeworx' and each sentence provides distinct information: beta status, similarity to stable version, source-preference ranking, usage instruction, and fallback. It is efficient but could be slightly more concise.

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 core routing functionality, the experimental improvements, and usage context. There is no output schema, but the description does not need to cover return values as it references the same response shape as ask_pipeworx. It is sufficiently complete for a beta 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 all parameters described as aliases for 'question'. The description does not add extra semantics beyond noting it accepts the same arguments as ask_pipeworx. Baseline 3 is appropriate as the schema already handles parameter documentation.

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 beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape, but with candidate routing improvements. It specifies the source-preference ranking feature and distinguishes from the stable version, making the purpose unambiguous.

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

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

The description explicitly advises using it exactly like ask_pipeworx when wanting the newest routing, and notes that results are compared against the stable router. It provides clear context for when to use this beta version, though it does not explicitly state when not to use it or list 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 and destructiveHint=false. The description adds value by detailing the exact return structure (answer, evidence, confidence, source, fetched_at, refusal_reason) and listing possible refusal reasons. 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 informative but somewhat verbose for a tool with detailed annotations and schema. It includes operational details that could be separated, but remains mostly readable and front-loaded with key 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 (refusal reasons, cost, behavioral constraints), the description covers most important aspects. No output schema exists, but the return format is described. Missing details on pagination or error handling beyond refusals, but still adequate.

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

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

Schema coverage is 100% with descriptions for all 6 parameters (aliases for 'question'). The description does not add new information beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose as a hallucination-resistant answer mode for high-stakes reads. It explains the process of routing, fetching data, and extracting answer only from tool result, distinguishing it from the sibling tool ask_pipeworx.

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

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

Explicit guidance is provided: use for high-stakes reads where answers will be quoted, cited, or acted on; prefer ask_pipeworx for casual lookups. Also mentions the cost of an extra LLM call, aiding decision-making.

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, idempotent, non-destructive behavior. The description goes far beyond these by detailing fan-out patterns, response shapes, resolver confidence levels, parent event extraction, news fallback fields, safety short-circuits, and cancellation rule parsing. 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 lengthy but well-structured: it opens with a clear purpose and usage, then systematically covers classifiers, fan-out examples, response shapes, resolver contract, and safety notes. Every section adds value, though some details could be consolidated for brevity.

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 thoroughly documents response sections, fields, error handling, and edge cases. It covers low-confidence matches, closed markets, wide spreads, cancellation rules, and news fallback behavior, making the tool fully understandable without additional references.

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 for all three parameters. The description adds context: it explains the market input variations, the depth enum defaults, and the include_raw effect on response size. Examples in schema further clarify usage, making the parameter semantics complete and actionable.

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: research a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison). It distinguishes from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on research and evidence gathering.

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

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

The description explicitly states when to use the tool: "Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'". It does not explicitly mention when not to use it or compare to alternatives among sibling tools, but the provided usage intent is clear and helpful.

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 a safe read operation; the description adds behavioral details: handles off-calendar fiscal years, sorts results by primary metric, returns paired data with citation URIs, and replaces many lookups. 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 front-loaded with trigger phrases and structured into purpose, entity-type details, and behavior. While slightly long, every sentence adds value. Minor redundancy in listing trigger phrases, but overall 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 no output schema, the description covers input parameters, entity-specific data sources, sorting behavior, and citation output. It also addresses edge cases (off-calendar fiscal years). Missing explicit return structure but adequate for agent understanding.

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 the description adds semantic context: explains what each entity type pulls (financials for company, adverse events for drug) and gives examples. This adds meaning beyond the schema's enum labels and array 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 performs side-by-side comparison of 2–5 companies or drugs, with specific verb phrases like 'Compare X and Y' and 'rank these companies'. It distinguishes between entity types (company: financials from SEC EDGAR/XBRL; drug: FAERS, FDA, trials) and differentiates from single-entity 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?

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving a strong directive on when to use this tool over alternatives. Also implies use for comparisons or rankings and notes it replaces many lookups.

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 account requirement, paid plan, expected response times, hop behavior, gap recovery, contradictions scan, semantic excerpting, and citation format. Adds substantial context beyond annotations (readOnly, openWorld, idempotent, not destructive) 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 verbose but well-organized with critical info upfront (account requirement and alternative). Every sentence adds value, though slight restructuring could improve readability for very long text.

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 thoroughly explains the return format (findings packet with evidence, confidence, source, citations, gaps, contradictions) and behavior across depths. No gaps remain for an agent to understand what to expect.

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

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

Schema covers both parameters (question and depth) with descriptions; the tool description enhances this by explaining depth levels in terms of number of facets and behavior (quick=3, standard=5 with gap recovery, thorough=8 with iterative hop), and clarifies that question can be broad/multi-part.

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

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

The description clearly states the tool performs grounded multi-source research across structured data sources, decomposing questions into facets and using parallel tools. It specifies it is not open-web search and distinguishes from alternatives like ask_pipeworx for single lookups or breaking news.

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 (broad/multi-part questions over structured data), when not to use (single lookup or breaking news), and provides specific sibling tool alternatives (ask_pipeworx). Also mentions account requirements and paid tier for 'thorough' depth.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds value by detailing the output format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas...ready to call directly.' 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 fairly comprehensive but not overly verbose. It front-loads the core purpose and then elaborates with examples and return format. Every sentence contributes value, though minor redundancy exists (e.g., listing domains twice).

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 (6 parameters, 1 required, no output schema), the description covers all essential aspects: purpose, usage, parameters, and return format. It is complete enough for an agent to understand and invoke correctly without additional 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 description coverage is 100% with each parameter documented. The description adds context beyond the schema by providing natural language examples and explaining that multiple aliases are accepted for the query parameter. This enhances understanding without redundancy.

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: 'Find tools by describing the data or task.' It lists specific domains and differentiates from siblings by emphasizing discovery of tools themselves, not answering queries directly. The instruction 'Call this FIRST when you have many tools available' further distinguishes it.

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 guidance: 'when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST...when you want to see the option set.' It lacks explicit when-not-to-use instructions but the context implies it is for initial exploration.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial context: it fans out across multiple sources, returns specific fields, notes that the USPTO PatentsView API sunset May 2025 (soft-fails), and uses a GDELT→GNews fallback. This goes beyond annotations to explain actual behavior and potential failures.

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 fairly long but front-loaded with concrete examples. It efficiently packs a lot of information into a single paragraph. While it could be slightly more structured (e.g., bullet points), it is still concise for the amount of detail provided and every sentence serves a 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 no output schema, the description thoroughly explains what the tool returns: CIK, company_name, recent_filings (with URIs), fundamentals, patents, news, LEI. It also warns about the patent data source sunset in May 2025. Given the complexity of the tool (multiple data sources), this description is complete enough for an agent to understand the output thoroughly.

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 has 100% coverage with descriptions for both parameters. The description adds value by reiterating that the 'value' parameter accepts ticker or zero-padded CIK and stating that names are not supported, which reinforces the schema. However, since schema coverage is already high, the baseline is 3; the extra context nudges it to 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 purpose: 'full cross-source profile of a US public company in ONE parallel call'. It lists concrete example queries and specifies the data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF). This distinguishes it from sibling tools that perform individual lookups (e.g., resolve_entity, search_within), making the purpose unambiguous.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides clear constraints: 'names not supported (use resolve_entity first if you only have a name).' This gives direct guidance on when to use this tool vs alternatives, which is exemplary.

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 destructiveHint=true and idempotentHint=true; description adds no further behavioral details beyond the basic delete action. Additional context about permanence or side effects is missing but not contradictory.

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 concise sentences, each earning its place: first for purpose, second for usage guidance.

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 1 parameter, 100% schema coverage, and no output schema, the description fully covers the tool's operation and usage 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?

The single parameter 'key' is fully described in the input schema. The description adds no extra semantic meaning beyond the schema's description.

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

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

The description uses a specific verb ('Delete') and resource ('memory by key'), clearly distinguishing 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?

Explicitly states when to use the tool ('context is stale, task done, clear sensitive data') and mentions paired tools ('remember', 'recall') for 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 indicate read-only, idempotent, and non-destructive behavior, which the description aligns with by mentioning fetching and extracting without mutation. The description adds process details (fetches page, extracts fields) that supplement the annotations well.

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 process and use cases. Every sentence adds value, no fluff, ideal length for an agent to quickly grasp.

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 adequately explains the output as a 'single text blob' and its intended location. All key aspects (input, process, output, use cases) are covered alongside comprehensive 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 both parameters described (url and max_links). The description only restates the default/max for max_links, not adding significant meaning beyond the schema. Baseline 3 is appropriate as schema does the heavy lifting.

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 a production-ready llms.txt file for any URL to aid AI crawlers. It specifies the action (generate), resource (llms.txt for a URL), and output format. This distinguishes it from siblings like 'scan_competitor_ai_presence' which focuses on scanning rather than generation.

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: getting a client's site indexed, drafting for own project, or auditing competitor perception. While it doesn't state when not to use, the context is clear and directly applicable.

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 value beyond annotations by detailing the return format (title, summary, type, link, last-updated time) and giving an example. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, which the description does not contradict.

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 efficient sentences plus an example, with the main purpose front-loaded. Every sentence serves a purpose: clarifying the tool's scope, specifying return fields, and providing a usage template. 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 tool with 1 optional parameter and no output schema, the description covers all necessary aspects: what the tool does, what data it returns, and an example call. It is complete given the low complexity and supportive 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% with the 'limit' parameter already well-described. The tool description does not add extra parameter semantics beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns 'Current disturbances, incidents, and planned works on the Belgian rail network' and lists specific attributes (title, summary, type, link, last-updated time). This distinguishes it from sibling tools like irail_journey (journey planning) and irail_liveboard (liveboard), which serve different purposes.

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

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

The description implies usage for retrieving current rail disturbances but does not explicitly state when to use this tool versus alternatives or provide exclusions. The example call 'irail_disturbances({})' gives a template but no further guidance on selection between 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 already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds that the tool provides 'live delays and platforms per leg' and mentions that times are 'interpreted in Belgian local time', which gives context beyond annotations. 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, using four sentences to convey purpose, examples, parameter details, and timezone handling. It is front-loaded with the main action and contains 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 has 5 parameters (2 required) and no output schema, the description explains input semantics well and indicates the output includes legs, transfers, delays, and platforms. It lacks specific return field details but is sufficient for an agent to infer the structure.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining datetime formats (ISO or time-only), default behavior for depart_at, and that arrive_by overrides depart_at. It also provides an example call, clarifying usage beyond schema definitions.

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 plans train journeys between Belgian stations with legs, transfers, live delays, and platforms. It uses specific verbs like 'plan' and 'route planner', and distinguishes itself from sibling tools like irail_liveboard (live departures) and irail_train (single train details).

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 concrete examples of use cases (e.g., 'next train from Brussels to Antwerp') and explains optional depart_at/arrive_by parameters. However, it does not explicitly state when not to use this tool or suggest alternatives among siblings, which would make it a 5.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context beyond annotations by detailing the specific data fields returned (train number, destination, scheduled time, delay, platform, canceled flag) and mentioning that station input is fuzzy. 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 two sentences long, front-loaded with the core purpose, followed by parameter details and an example. 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?

Despite no output schema, the description lists the fields returned (train number, destination, scheduled time, delay, platform, canceled flag), providing sufficient context. The input parameters are fully explained, making the tool understandable 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 coverage is 100%, and the description adds significant meaning: it explains that the 'station' parameter accepts English exonyms and fuzzy input, provides examples, and clarifies the 'type' parameter for switching between departures and arrivals. The 'limit' parameter is described in the schema, so no additional detail needed.

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 provides a live departures board for Belgian train stations, listing departures with specific fields like train number, destination, scheduled time, delay, platform, and canceled flag. It also notes the tool can be used for arrivals by setting type to 'arrival', distinguishing it from sibling tools like irail_journey or irail_disturbances.

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 how to use the tool for departures or arrivals, and notes that station names accept English exonyms and fuzzy input. It provides an example call. However, it does not explicitly state when not to use this tool versus alternatives like irail_journey for journey planning.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context about output details (per-stop delays, platforms, live position) and input formats, providing value 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?

Two sentences with no waste. The first sentence front-loads the core purpose and key outputs. The rest provides input format guidance and an example, making it easy to scan.

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

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

No output schema is provided, but the description comprehensively lists what the tool returns: scheduled vs actual times, per-stop delay, platforms, current delay, and live position. For a simple 2-parameter tool with no nested objects, this is 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 coverage is 100% for both parameters (id and date). The description adds meaning by explaining acceptable id formats (e.g., 'IC 1832', 'BE.NMBS.IC1832') and that date defaults to today in Belgian time, which enhances schema 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 it tracks one Belgian train by number, listing all stops with scheduled/actual times, delays, platforms, and live position. It distinguishes itself from sibling tools like irail_liveboard and irail_journey by specifying that train numbers come from those tools.

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

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

The description indicates when to use this tool (track a specific train) and mentions that train numbers come from irail_liveboard or irail_journey, implying alternatives. However, it does not explicitly state when not to use it or compare to other tools like irail_disturbances.

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, idempotentHint=true, so the description's behavioral contribution is minimal. It adds the return fields but does not elaborate on potential side effects or behavior beyond the annotation hints.

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

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

Two concise sentences with no wasted words. First sentence states purpose and output, second provides usage guidance. Front-loaded with the key action and scope.

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, good annotations, and no output schema needed, the description is complete. It covers what the tool does, what it returns, and when to use it.

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 parameter 'include_inactive' is fully described in the schema. The description does not add new information about the parameter beyond implying it by saying 'active subscriptions'. 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 states the verb 'list' and the resource 'subscriptions', specifying it returns caller's active subscriptions with a field list. It distinguishes from siblings like 'subscribe' and 'unsubscribe' by focusing on viewing existing subscriptions.

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 usage scenarios: 'review what you're monitoring before adding more or to find an id to cancel'. This helps the agent decide when to use this tool. It could mention when not to use it, but the positive guidance is 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 are all false, but the description adds critical behavior: rate-limited to 5 per identifier per day, free (doesn't count against quota), and daily review by the team. This context far exceeds the annotations' minimal disclosure. 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 with no redundant sentences. It front-loads the purpose, then provides clear guidelines, constraints, and context. Every sentence earns its place without being verbose.

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

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

For a 3-parameter tool with enum and nested objects, the description covers usage, rate limits, what to include (be specific about tool/error), and what not to include (end-user prompt). No output schema is needed for a simple feedback tool. The context is fully 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%, so baseline is 3. The description enriches meaning by explaining enum values in more detail ('bug = something broke or returned wrong data') and clarifying the context field's purpose. However, the schema already provides adequate descriptions, so the addition is helpful but not essential.

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 the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses specific verbs and clearly identifies the resource (Pipeworx team feedback). It distinguishes itself from sibling tools by focusing solely on feedback submission, not queries or actions.

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 detailed when-to-use guidance for each feedback type (bug, feature, data_gap, praise, other) and explicitly states what not to do: 'don't paste the end-user's prompt.' It also mentions rate limits and quota-free usage, leaving no ambiguity about appropriate use.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds caching duration (5min-1h), data source (CF analytics-engine), and no-PII guarantee. 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 well-structured sentences plus a bullet list. Information is front-loaded with main purpose, 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?

Given single optional parameter and no output schema, description fully explains return values, source, caching, and use cases. Complete for a read-only trending 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?

Only parameter 'window' has full schema description coverage. Description adds nuance (shorter windows for hot, longer for steady-state), enhancing schema 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?

Description clearly states it returns top tools, packs, and call volume over a window. Verb 'returns' and resource specification are precise, and the tool is well-distinguished from siblings like 'discover_tools' and 'ask_pipeworx'.

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?

Three explicit use cases are listed (discovering hot sources, confirming canonical choice, checking alignment). Window-specific guidance is provided. Lacks explicit when-not-to-use or direct alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint. The description adds extensive behavioral context: internal algorithms (partition_check, monotonicity checks), semantic anchor (Jaccard similarity), partition filter (placeholder fraction), and fill check mechanics (theoretical vs realizable edge). 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 long but well-structured with section headings (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence is informative, though it could be slightly more concise. Still effectively front-loaded with the core function.

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 explicitly documents the response structure: opportunities[] with fields (gap_pp, suggested_trade, reasoning, monotonicity violation context) and partition_check details for event mode. Combined with the detailed behavioral descriptions, the tool is fully understood for 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 description coverage is 100%, but the description adds significant value beyond the schema: provides concrete examples of event slugs ('fed-decision-may-2026'), topic seed questions ('Strait of Hormuz ...'), explains that full URLs are accepted, and clarifies the behavioral difference between the two modes.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This is a specific verb+resource+method. It distinguishes itself from siblings like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection.

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 and how to use each mode: 'Call with NO args for a `trending_scan`', '`event` (recommended for a specific market)', '`topic` (for cross-event scanning)'. Also warns against trading when fill check fails: 'do not trade 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 already mark it read-only and idempotent. The description adds deep behavioral context: caching, model families, segments, diagnostics, and edge definition. 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 very long and detailed. While every sentence adds value, it is not concise. For a complex tool, some length is justified, but it could be more streamlined.

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 complexity, no output schema, and 9 parameters, the description is remarkably complete. It explains output structure, internal logic, edge cases (empty segments), and knobs thoroughly.

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 good descriptions. The main description does not add extra parameter meaning beyond what the schema provides. Baseline score of 3 is appropriate.

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

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

The description states the specific verb 'scan' and 'return' with a clear resource: 'Polymarket markets'. It distinguishes from sibling tools like polymarket_arbitrage by focusing on Pipeworx data disagreement. The purpose is immediately identifiable.

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 knobs for filtering. However, it does not directly compare to alternatives or say when not to use it, though the context is clear.

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 behavior. The description adds valuable context: history depth bounded by 60-day TTL, decay from daily closes not intraday, and explains response structure (tracked, expired, snapshot_dates). 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?

The description is somewhat lengthy but well-structured, front-loading the core question and then detailing parameters, response, and limits. Every sentence adds value; could be slightly more concise but not overly verbose.

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 exists, so the description fully explains the return structure (tracked, expired, snapshot_dates) with field details and limits. Given the tool's complexity (time-series analysis), it is complete and covers edge cases (gaps, TTL).

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 both parameters with descriptions and defaults (100% coverage). The description repeats some defaults but does not add new semantic meaning. 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 states it provides edge persistence and decay telemetry, answering a specific question about edge duration. It distinguishes itself from the sibling tool 'polymarket_edges' by focusing on historical time-series rather than current snapshots.

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 concrete use case (comparing fresh vs old wide edges) and implies when to use it (for historical persistence analysis). It does not explicitly state when not to use or list alternatives, but the context provided is sufficient.

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, idempotentHint, etc.) already indicate safety. Description adds key behavioral context: walks order-book ladder, returns fill metrics (vwap_fill_price, slippage), warns about thin books and directional risk, and details return fields. 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?

Description is comprehensive but slightly verbose, yet every sentence adds value. Structured with bold tags for modes and clear sections. Could be trimmed slightly but remains highly informative 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?

Despite no output schema, description fully explains all return fields and their meanings for both modes. Covers defaults, limits, warnings, and edge cases like directional risk. Complete given the tool's complexity.

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

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

Schema covers all 4 parameters with descriptions, but description adds significant meaning: explains dual-mode behavior, default side selection (auto), interpretation of size_usd in basket mode as settlement notional, and clamps. Goes well beyond schema alone.

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 performs a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes from siblings by explicitly directing use before polymarket_arbitrage or polymarket_edges trades above ~$500, making its purpose unique and clear.

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

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

Explicitly tells when to use: before arbitrage or edge trades above ~$500. Explains single-market vs basket mode, required parameters, default behaviors, and warns against partial basket fills converting arb into unhedged positions. Provides comprehensive guidance.

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

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

The description adds significant behavioral context beyond annotations, detailing compatibility_warning conditions, temporal alignment constraints, and skipped cross-type/subtype counters. It discloses that real spreads are rarer than suggested, which is critical for accurate tool invocation.

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 lengthy, with multiple paragraphs and technical details. While well-structured into sections, some brevity could be improved without losing essential info.

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 cross-venue spread calculation and the lack of an output schema, the description very thoroughly explains all return fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). No gaps identified.

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 and examples. The description enriches parameters by explaining how topic auto-fetches and explicit overrides work, and listing the specific topic values. Adds value beyond schema alone.

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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question, specifying two modes (topic and explicit) and distinguishing itself from sibling tools like compare_entities and 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 explains when to use topic mode vs explicit mode, and warns that most pre-mapped topics return compatibility_warning. However, it does not explicitly state when not to use the tool 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, ensuring the agent knows this is a safe, read-only operation. The description adds behavioral context such as listing all keys when omitted and scoping to identifiers, which is useful but not essential given the annotations.

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

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

The description is concise (three sentences) and front-loaded with the core purpose. Each sentence adds value: purpose, usage examples, and pairing guidance. 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?

For a simple tool with one optional parameter and no output schema, the description covers all needed context: retrieval vs listing, scoping, and pairing with sibling tools. Annotations cover safety, making the description complete for effective 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?

The input schema already has 100% coverage for the single optional 'key' parameter, with a clear description. The description restates the parameter behavior (omit to list keys) but does not add significant new meaning beyond what the schema provides. Baseline of 3 is appropriate.

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

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

The description clearly states the tool retrieves a value saved via 'remember' or lists all saved keys when the key argument is omitted. It uses a specific verb (retrieve/list) and resource (saved values), and distinguishes from sibling tools 'remember' and 'forget' by naming them 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?

The description explains when to use the tool ('look up context the agent stored earlier') and provides guidance on pairing with 'remember' to save and 'forget' to delete. It also clarifies scoping to the agent's identifier, giving clear context for appropriate use.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that events carry source, citation_uri, and raw payload, and explains the mark_read flag behavior, which 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?

Three sentences front-loading the purpose, with no wasted words. Every sentence serves a clear informational 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?

Given no output schema, the description explains the return structure and key behaviors (mark_read, polling, alternative endpoint). It is thorough for a read-only tool with comprehensive 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%, so baseline is 3. The description provides an example for type ('sec_8k') and explains mark_read effect, but does not mention limit or unread_only, adding limited extra value.

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 pulls fired events from a subscription feed, returning recent alerts with source, citation_uri, and raw payload. It distinguishes itself from siblings by focusing on alert retrieval, not subscription management.

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 context on when to use (polls work fine) and mentions the same feed is available via a direct API endpoint for scripts/dashboards. However, it does not explicitly exclude other tools or give alternatives 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?

Annotations indicate safe read operation. Description adds crucial behavioral details: fans out to multiple sources (SEC, GDELT/GNews, USPTO), GDELT preferred with GNews fallback, USPTO soft-fails. 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 front-loaded with example queries and covers all necessary info. It is slightly long but 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?

Given 3 params, 100% schema coverage, no output schema, the description explains return structure (changes[] grouped by source, total_changes, citation URIs) and covers fallback and limitations. Complete for the tool's complexity.

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

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

Schema coverage is 100%. Description explains all three parameters with examples: 'since' accepts ISO date or relative shorthand, 'value' is ticker or CIK, 'type' is limited to 'company'. Provides recommended values for monitoring.

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 provides a 'change feed for a company' and lists specific example queries. It explicitly distinguishes from sibling tool '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?

The description explicitly tells when to use this tool (for recent changes) and when to use entity_profile instead. It also explains fallback behavior and date shorthand.

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 goes beyond annotations by disclosing that memory is scoped by the agent's identifier and that persistence differs for authenticated users (persistent) vs anonymous sessions (24 hours). This is critical context that annotations (idempotentHint, destructiveHint) do not cover.

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 (4 sentences) and well-structured: purpose first, then usage guidance, then behavioral detail. Every sentence adds value. Slightly more verbose than the calibration 'HIGH' example, but still efficient.

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 two simple string parameters and no output schema, the description is fairly complete: it explains storage scope, persistence behavior, and relationships to sibling tools. It could add a note about the maximum size or format of values, but that is a minor gap.

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

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

The input schema already covers both parameters with descriptions. The description adds conceptual context ('key-value pair scoped by your identifier') but does not add much beyond the schema. With 100% schema coverage, baseline 3 is appropriate.

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

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

The description starts with a clear verb and resource: 'Save data the agent will need to reuse later.' It distinguishes from siblings recall and forget by explicitly mentioning the pairings, and contrasts with the broad set of sibling tools that do other things like search or research.

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

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

The description provides explicit guidance on when to use this tool: 'when you discover something worth carrying forward.' It also mentions pairing with recall and forget, giving context on the lifecycle. No explicit when-not is given, but the use case is well defined.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds that it 'cascades through several lookup endpoints internally' and details the exact return values for each type (e.g., ticker, CIK, citation URI for company; RxCUI, ingredient, brand for drug). 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 front-loaded with clear examples and a directive. It is structured with bullet-like points for supported types. Every sentence adds value, though slightly verbose; could be trimmed without loss.

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 resolution tool with two parameters and no output schema, the description comprehensively covers what it does, what identifiers it returns, and the internal cascading logic. It is complete enough for an agent to select and 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% with both parameters described. The description adds contextual examples for 'value' (e.g., 'ticker (AAPL)', 'CIK (0000320193)', 'brand or generic name') and clarifies the enum 'type' values, enhancing usability 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 opens with concrete user queries ('What's the ticker for...', 'find the CIK for...'), clearly defining the tool's purpose as resolving names to canonical identifiers. It also explicitly distinguishes from sibling tools by stating 'Use FIRST whenever you have a name but need an ID.'

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 instructs 'Use FIRST whenever you have a name but need an ID.' It lists supported entity types and the corresponding identifiers resolved. While it does not explicitly state when not to use, the instruction is clear and provides context for when this tool is the primary choice.

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, idempotent, non-destructive. Description adds it calls ai_visibility_check per entity, ranks results, and returns score/confidence/signal density. 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 concise sentences, front-loaded with main purpose, no extraneous 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?

No output schema, but description outlines return structure (ranked list, score, confidence, signal density). Covers all parameters and usage context adequately for the tool's complexity.

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

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

Schema covers all 4 parameters with descriptions. Description adds value by explaining entities[0] is 'subject', and that models defaults to workers-ai. Provides extra 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?

The description specifies the verb 'Compare', resource 'AI visibility', and action 'side-by-side' across multiple entities. It clearly distinguishes from sibling tool ai_visibility_check by aggregating results.

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 case ('competitive AI-marketing audits') and example query. Does not explicitly state when to avoid or name alternatives, but context is clear.

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. Description adds context on composite call, partial failures, bundlephobia timing, and return structure, enriching behavioral understanding 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?

Description is detailed but front-loaded with the core action. Some sentences could be combined for brevity, but structure is logical and each part serves a 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 no output schema, the description thoroughly explains the return structure (summary block, advisories, links, alternatives) and covers edge cases like partial failures and timing, making it complete for a complex 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 clear descriptions for both parameters. Description adds nuance about scoped packages and default version behavior, providing marginal extra value.

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's a composite check for npm package safety, popularity, and size, distinguishing it from related tools like 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 specifies when to use (when agent asks 'is X safe/popular/small' or 'what does adding lodash cost me') and the scope (NPM only, with fallback to deps.dev for other ecosystems).

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?

Even with comprehensive annotations (readOnlyHint, openWorldHint, etc.), the description adds significant technical detail: embedding model (BGE-base-en), window size (500-char overlapping), similarity measure (cosine), and character cap (200K chars with truncation flag). 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 single-paragraph description is front-loaded with purpose, immediately followed by usage guidance, then technical details. Every sentence contributes unique information with no redundancy.

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

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

Given no output schema, the description adequately explains the return (top-N passages with offsets and scores). For a 3-parameter tool, it covers the behavior, constraints, and integration context fully.

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 is 3. The description adds value beyond schema by explaining the 'max ~200K chars' context for 'text', the default for 'limit', and providing concrete query examples for 'query', making parameter usage clearer.

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 performs semantic search inside a fetched record, using specific terms like 'passages', 'character offsets', and 'similarity scores'. It distinguishes from sibling tools by mentioning pairing with ask_pipeworx_grounded and by the core action of searching within a record.

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 context for when to use: 'Use when the record is too big to cram into the prompt'. It also suggests pairing with another tool, but does not explicitly state when not to use or list alternatives beyond the one mentioned.

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

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

Annotations indicate readOnlyHint=false (mutating), idempotentHint=true, destructiveHint=false. The description adds behavioral details: requires OAuth, returns subscription ID, delivery channel behaviors (always-on feed, email/SMS caps, webhook with HMAC signing and auto-disable). This goes beyond annotations, though it could mention rate limits or idempotency semantics more explicitly.

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 and front-loaded with the core purpose. It covers types and delivery in separate paragraphs. While somewhat lengthy, every sentence adds value. Could be slightly more concise 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 the tool's complexity (multiple types, delivery options, prerequisites), the description is comprehensive. It covers account requirements, type-specific details, delivery features, and limitations (SMS cap, webhook auto-disable). No output schema, but it mentions the return value. Missing explicit guidance on using the returned subscription ID.

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 3. The description adds significant meaning: detailed examples for each subscription type's params (e.g., sec_8k with items code, polymarket_edge with topic), and delivery object details (email validation, SMS verification, webhook signing secret and auto-disable). This far exceeds 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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation. The verb 'create' and resource 'subscription' 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 provides explicit context for when to use this tool (creating a subscription) and lists prerequisites (Pipeworx OAuth account) and restrictions (anonymous/BYO cannot persist). However, it does not explicitly state when not to use it or mention alternatives, though the context is clear.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context that it's an onboarding entry point and returns example questions with tool+argument shapes, but the core behavioral traits are covered by annotations.

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

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

The description is front-loaded with purpose and usage, organized with examples. It's somewhat long but each sentence adds value. Could be slightly more concise, but structure is good.

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, so description must explain return value. It does so clearly: 'Returns category-bucketed example questions... each with the exact tool + argument shape'. Also covers both usage modes (no args vs topic). Sufficient for a simple retrieval 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 one optional parameter 'topic'. The description adds meaning by listing valid values (finance, pharma, etc.) and explaining the effect of omitting vs providing topic. This goes beyond the schema's short description.

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

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

The description clearly states the tool returns category-bucketed example questions for onboarding, with specific verb 'returns' and resource 'example questions'. It distinguishes from siblings like ask_pipeworx (which answers questions) and discover_tools (which might list tools differently).

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 this FIRST when you do not yet know what Pipeworx can do for you' and explains when to use topic parameter vs no arguments. Also references meta-tools as 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 ownership enforcement and deactivation (not deletion) beyond annotations, which already indicate non-destructiveness and idempotency. 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 concise sentences that front-load the purpose and efficiently convey all necessary details without 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), the description fully covers purpose, usage constraints, and behavioral implications, leaving 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 coverage is 100% with a clear description for the single 'id' parameter. The tool's description adds no additional meaning beyond what the schema provides, meeting the baseline but not exceeding it.

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

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

The description clearly states the action ('Cancel a subscription by id') with a specific verb and resource, effectively distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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 mentions ownership enforcement ('you can only cancel your own subscriptions') and the soft-delete behavior, providing clear context on when to use and what to expect, with no need for alternative references.

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, and non-destructive. The description adds value by detailing the two verification pipelines (SEC EDGAR vs. grounded), exact percent-delta math, and the return format with citations and reasoning.

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 slightly long but every sentence adds value, covering usage, behavior, and returns. It is well-structured with bullet-point-like 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?

Given only two parameters and no output schema, the description fully explains the return values (verdict, actual value, citation, reasoning) and covers both verification paths, making it 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% and the description adds examples for the 'claim' parameter and explains the 'tolerance_pct' parameter's default and use case, going 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 is for natural-language claim verification against authoritative sources, with specific verbs like 'Is it true that...' and 'fact check'. It distinguishes from sibling tools by noting it replaces 4–6 sequential calls.

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 whenever the agent needs to check whether something a user said is factually correct' and explains two verification paths. It provides clear context but does not list when not to use.

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