Monarch Initiative

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint. The description adds that it probes models (non-destructive), returns per-model scores and raw responses, and notes that Anthropic calls require user's own API key (paid 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 concise (4 sentences) and front-loaded with the main purpose. It efficiently includes key details without unnecessary verbosity. Slightly more detail than strictly needed but still effective.

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

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

Given 4 parameters, 100% schema coverage, no output schema, the description adequately covers return structure (per-model {score, confidence, signals, raw_response} + combined view). It is complete enough for an agent to understand tool behavior and output.

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%. The description adds meaning beyond the schema by explaining the default model for 'models', the purpose of '_apiKey' for Anthropic billing, and that 'context' helps disambiguate. All parameters are well-explained.

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 knowledge about an entity and scores visibility (0-100). It uses specific verb 'probe' and resource 'LLMs', and distinguishes itself from siblings by focusing on AI visibility scoring rather than general search or entity lookup.

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

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

The description explicitly mentions use cases like AI-marketing audits, pre-launch brand checks, and competitive monitoring. It provides clear guidance on default model and optional Anthropic probe with API key, but does not explicitly state when not to use or detail exclusions.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavior context: routes to 4,819 tools, returns structured answers with pipeworx:// citation URIs, works on every tier, and is a single 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?

The description is front-loaded with the most important guidance (prefer over web search). It provides comprehensive information without unnecessary fluff, but is slightly verbose with many examples; could be a bit 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?

Given the complexity (6 parameters, 1 required), high schema coverage, no output schema, and annotations, the description is very complete. It explains when to use, what it returns (structured answer with citations), and how it works. 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 description coverage is 100% with clear parameter descriptions and multiple aliases. The description does not add extra semantics 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 answers factual questions using a large set of verified sources, with explicit mention of preferring over web search for specific domains. It provides numerous examples, 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 gives explicit when-to-use and when-not-to-use guidance, including alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions). It also states 'START HERE for most questions', providing a clear entry point.

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

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

Discloses return format with evidence, confidence, refusal reasons, and mentions cost (one extra LLM call). Annotations already indicate read-only, idempotent, non-destructive, and open-world, so description adds valuable context beyond that 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 well-structured with key information upfront, though somewhat lengthy. Every sentence adds value, explaining behavior, use cases, and trade-offs. Could be slightly more concise but overall 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 the tool's complexity (routing through many sources, extracting answers), the description is comprehensive. It covers return format, refusal reasons, use cases, and trade-off vs sibling. No output schema exists, but the description explains the output structure clearly.

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. The description adds 'Your question in natural language' which is sufficient, and the parameter semantics are clear from the schema. Slightly above baseline because the description hints at how the question is used in the grounded extraction process.

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 as a 'hallucination-resistant answer mode for high-stakes reads' and contrasts it with ask_pipeworx, which is a sibling tool for casual lookups. It specifies the exact process of routing, fetching, and extracting answer only from tool result.

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

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

Explicitly tells when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and gives specific examples. Also advises to prefer ask_pipeworx for casual lookups, providing clear differentiation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no behavioral context beyond 'Fetch', which is consistent. No further detail is needed but also no extra value.

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

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

The description is a single, well-structured sentence that concisely conveys action, resource, identifier, and filters. No wasted words; every element adds clarity.

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

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

Given 5 parameters (1 required), 60% schema coverage, and an output schema, the description covers essential usage. It could mention default direction or limit, but the output schema handles return format.

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

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

Schema coverage is 60% with descriptions for three of five parameters. The description lists filters (category, predicate, direction) and gives an example CURIE, but does not explain 'limit' or the format of 'entity_id' beyond example. Adds moderate semantic 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 verb 'Fetch', the resource 'biolink associations (edges)', and the specific identifier format 'CURIE ID'. It distinguishes itself from sibling tools like 'entity' (which fetches nodes) by focusing on associations.

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 specifies filters (category, predicate, direction) and implies usage for querying associations of a given entity. It doesn't explicitly contrast with alternatives, but 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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes far beyond, detailing resolver confidence levels, parent event extraction, safety short-circuits, closed market handling, wide-spread warnings, and resolution rules. 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, but not concise. It contains a lot of valuable information in a rambling structure. A more organized format (e.g., sections) would improve conciseness while retaining completeness.

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

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

The description covers all relevant aspects: input flexibility, classifier categories, fan-out examples, response shape details, resolver contract, parent event extraction, news fallback, safety mechanisms, market state handling, and resolution-rule risk. It is fully sufficient for correct tool invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the market parameter can be a slug, URL, or question, and by providing examples. It also elaborates on the depth and include_raw parameters beyond the schema descriptions.

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

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

The description explicitly states the tool researches Polymarket bets by pulling Pipeworx data, with clear verb+resource. It explains the input (slug, URL, question) and output (evidence packet, comparison). The purpose is distinct from sibling tools like polymarket_edges or search.

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 use cases (e.g., 'should I bet on X', 'what does the data say about Y'), and includes examples of fan-out per category. However, it does not explicitly compare to sibling tools or state when not to use it, which would improve guidance.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds specific behavioral details: it pulls latest 10-K data from SEC EDGAR/XBRL, handles off-calendar fiscal years correctly, returns sorted results, and provides citation URIs.

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 example queries. Every sentence adds value, though it could be slightly more concise. Still, it effectively communicates all necessary information.

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

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

Despite no output schema, the description explains what is returned (paired data, citation URIs, sorted by primary metric) and covers input details, data sources, and fiscal year handling. It is complete for a comparison tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the entity types (company vs drug) and giving examples of valid values (tickers/CIKs for companies, drug names). This extra context justifies a 4.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It provides specific verbs like 'compare' and 'rank', and distinguishes it from sibling tools by focusing on parallel comparisons rather than sequential lookups.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides example queries and clarifies when to use type='company' vs type='drug', giving strong context for tool selection.

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

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

Annotations already mark the tool as read-only, idempotent, and not destructive. The description adds valuable behavioral context: expected 15-60s response time, returns a findings packet with verbatim evidence, confidence, source, fetched_at, and pipeworx:// citations, with explicit gaps[]. It also explains the parallel decomposition process.

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 and front-loaded with critical info (account requirement). Every sentence adds value, though it could be slightly more concise without losing clarity.

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

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

Given the tool's complexity, the description is highly complete: it explains the process, return format, limitations (gaps for non-structured topics), timing, and prerequisites. No output schema exists, so the description adequately covers return values.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema by explaining the depth enum values (quick=3, standard=5, thorough=8) and clarifying that the question can be broad or multi-part. This helps the agent make better parameter choices.

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: grounded multi-source research across Pipeworx's 1259 structured data sources, decomposing questions into facets and routing to 4,819 tools in parallel. It distinguishes itself from siblings like ask_pipeworx by specifying that it is best for broad/multi-part questions and not for single lookups or current 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?

The description provides explicit guidance on when to use this tool versus alternatives: if not signed in, use ask_pipeworx; for a single lookup, use ask_pipeworx; for breaking/current-news, prefer ask_pipeworx. It also notes that 'thorough' depth requires a paid plan.

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

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

Adds useful context beyond annotations: returns top-N tools with schemas and curated examples, ready to call directly. No contradiction with readOnlyHint etc.

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

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

Single paragraph, front-loaded with purpose, informative yet concise, every sentence adds value.

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

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

Fully explains what the tool does, when to use it, what it returns, and provides examples. No output schema needed as description covers return behavior.

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

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

Schema covers all parameters with descriptions (100% coverage). The description adds minimal extra semantics, just restating that query accepts natural language.

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 finds tools by describing data or task, lists many domains, and distinguishes from sibling tools like 'search' and 'deep_research' by focusing on tool discovery.

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

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

Explicitly advises to call this FIRST when many tools are available and you want to see the option set, providing clear when-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false. The description adds minimal behavioral context (a simple lookup), which is consistent. However, it does not disclose edge cases or error handling.

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

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

The description is a single sentence that is front-loaded with the core purpose. No superfluous words or structural issues.

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 output schema (not shown but present) and rich annotations, the description is minimally adequate. However, it does not explain what a 'node' represents or how to interpret the result, and the sibling list includes similar tools, leaving the agent to infer nuances.

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 0%, but the description adds meaning to the 'id' parameter by specifying it is a curie and providing a concrete example ('MONDO:0007947'). This clarifies the expected input format beyond the type string.

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 'Single node by curie' clearly states the action (retrieve a single node) and the identifier format (curie). It provides an example ('MONDO:0007947'), but does not differentiate from sibling tools like 'entity_profile' or 'resolve_entity'.

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

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

No guidance on when to use this tool versus alternatives. The description lacks context about prerequisites, exclusions, or situations where other tools (e.g., 'resolve_entity') would be more appropriate.

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 true and destructiveHint false. The description adds valuable behavioral context: fans out across multiple sources, mentions patents soft-failing, specifies that names are not supported, and lists return fields. 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 relatively long but front-loaded with the purpose and example queries. Every sentence provides necessary information (use case, data sources, limitations). It could be slightly more concise, but overall it is well-structured and informative.

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

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

Given the tool's complexity (multi-source, multiple return fields) and the absence of an output schema, the description covers all necessary aspects: what it returns, sources used, limitations (patents sunset, no names), and parameters. It is complete enough for an agent to understand the tool's capabilities.

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% (both parameters have descriptions). The description adds clarity: 'type' is only 'company' now, and 'value' must be ticker or CIK, not names. While helpful, it does not go beyond the schema's basic meaning significantly, so a 4 is appropriate.

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

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

The description uses a specific verb and resource: 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes from chaining single-pack lookups by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' The example queries further clarify the intended use.

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 ('ALWAYS PREFER...') and provides alternative: 'use resolve_entity first if you only have a name.' It also lists example queries illustrating appropriate usage contexts.

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 destructiveHint=true and idempotentHint=true. The description adds behavioral context about when deletion is appropriate (stale context, task done, sensitive data), supplementing the annotations without contradicting them.

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

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

The description is two sentences, front-loads the core action, and contains no extraneous information. Every sentence adds value, making it highly concise 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 the simple tool with one parameter, no output schema, and comprehensive annotations, the description covers purpose, usage context, and sibling relationships completely. No additional information is needed.

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 the 'key' parameter already described as 'Memory key to delete'. The description does not add extra parameter details beyond 'by key', so no additional value is provided 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 'Delete a previously stored memory by key,' specifying the verb and resource. It distinguishes from sibling tools by mentioning 'remember' and 'recall', making its purpose unambiguous.

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

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

The description explicitly lists when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data.' It also suggests pairing with 'remember' and 'recall', providing useful context for when to use 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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral details beyond annotations: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' 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 three sentences: first states purpose and audience, second explains process, third gives output and use cases. Efficient, front-loaded with essential information, no wasted words.

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

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

Given the simple tool with 2 parameters and no output schema, the description fully covers what the tool does, how it works, and the output format ('single text blob ready to drop at site-root/llms.txt'). Use cases are also provided. No further detail needed.

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

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

Schema description coverage is 100%, baseline 3. The description adds context by mentioning 'production-ready', AI crawler names (ChatGPT, Claude, Perplexity), and the process involving fetching and extracting, which goes beyond the schema's parameter descriptions. It also provides examples for the url parameter and default/max for max_links.

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 generates a production-ready llms.txt file for any URL, specifying the verb 'generate', the resource 'llms.txt file', and the scope 'for any URL'. It distinguishes from siblings by focusing on llms.txt generation versus other AI visibility or scanning 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 lists explicit use cases: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing competitor AI crawler view. While it doesn't provide explicit when-not-to-use or alternatives, the sibling context offers implicit differentiation, making usage 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, openWorldHint, idempotentHint, and destructiveHint, so the description adds only the ID format clarification. No additional behavioral traits (e.g., result limits, caching) are disclosed.

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

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

The description is a single sentence with no unnecessary words. It is concise and front-loaded.

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

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

Given the presence of an output schema, the description does not need to explain return values. It covers the core mapping adequately. However, it could mention any scope limitations (e.g., human genes only) for full completeness.

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

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

The schema has 0% description coverage, but the description adds valuable semantics by specifying the expected ID formats (NCBIGene:... or HGNC:...). This compensates for the lack of schema parameter descriptions.

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

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

The description clearly states the tool's purpose: retrieving diseases associated with a gene. It specifies accepted ID formats (NCBIGene or HGNC) and distinguishes itself from the sibling tool 'phenotype_to_gene' which does the reverse.

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

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

The description implies when to use (when you have a gene ID and want diseases) but provides no explicit guidance on when not to use or alternatives beyond the sibling name. Usage context is implied but not stated.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds default behavior (active only) and return fields 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?

Two sentences, front-loaded with purpose and details. 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 read-only tool with no output schema, description lists return fields and explains parameter. Covers all necessary 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 already fully describes the single boolean parameter. Description mentions 'active' vs inactive but no additional semantics beyond schema.

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

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

Clear verb 'List' with specific resource 'subscriptions' and scope 'active'. Distinguishes from siblings subscribe/unsubscribe.

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: 'review what you're monitoring before adding more' and 'find an id to cancel'. Lacks explicit when-not, but sufficient 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?

The annotations already declare the tool as read-only, idempotent, open-world, and non-destructive. The description does not contradict these hints but also adds no further behavioral context (e.g., that results may vary over time due to ongoing annotations). Since the annotations provide sufficient behavioral transparency, the description is merely neutral, neither enhancing nor detracting. Score 3 is appropriate as the description carries the minimum burden.

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

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

The description is extremely concise, consisting of a single sentence. It is front-loaded with the core purpose. However, it might be too brief, lacking any supplementary information that could aid comprehension without adding significant length. Given the simplicity of the tool, this level of conciseness is acceptable and close to optimal.

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, output schema present, rich annotations), the description provides a minimal but functional understanding. It does not elaborate on what the response contains (e.g., gene symbols, IDs, or full objects), but the output schema likely handles that. For a straightforward lookup, the description is complete enough, though it could briefly mention the nature of the returned data.

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

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

The input schema has 0% description coverage, so the description must clarify the parameter. It mentions 'HP:… id' which hints at the expected format, and the example in the schema provides 'HP:0000118'. However, it does not explicitly state that the parameter must be a valid Human Phenotype Ontology ID string, nor does it describe allowed values or constraints. For a single required parameter, the guidance is adequate but not thorough.

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 indicates that the tool retrieves genes associated with a given phenotype ID. The resource (genes) and input (phenotype ID) are specified. However, it omits an explicit verb like 'retrieve' or 'get', and could be slightly more precise. It distinguishes from the sibling 'gene_to_disease' which goes in the opposite direction.

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

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

The description provides no usage guidelines, such as when to use this tool versus alternatives, nor any prerequisites or limitations. For instance, it doesn't mention that the phenotype ID must be from the Human Phenotype Ontology, nor does it direct users to other tools for reverse lookup (e.g., gene_to_disease). The agent must infer appropriate usage solely from the tool name and minimal description.

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?

While annotations are minimal, the description adds important behavioral details: rate-limited to 5 per identifier per day, free, doesn't count against quota, and daily team review. 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 concise (4-5 sentences) with no extraneous words. Front-loaded with purpose, followed by usage examples and constraints.

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 feedback tool with no output schema, the description covers all necessary aspects: types of feedback, required message specifics, context fields, rate limits, and quota impact. Complete and self-contained.

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

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

Schema covers 100% of parameters, but description adds valuable usage guidance: 'describe the issue in terms of Pipeworx tools/packs' and prohibited content. This context helps agents use parameters correctly beyond the 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 the tool is for sending feedback about bugs, missing tools, or praise. It uses specific verbs like 'tell' and provides examples, distinguishing it from sibling tools that handle queries or data retrieval.

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

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

Explicitly defines when to use (bug, feature, data_gap, praise) and what not to do (avoid pasting end-user prompts). However, it does not directly compare to sibling tools or state when not to use it, though the context makes it 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: self-aggregating signal derived from CF analytics-engine, no PII, caching behavior (5min-1h). 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 front-loaded with the core functionality in the first sentence, followed by bullet-like use cases and supplementary info (data source, caching). It is informative without being verbose, though slightly longer than strictly necessary.

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 clearly states what is returned (top tools, top packs, total call volume). Combined with annotations covering safety and caching details, it provides complete context for a simple tool with one optional parameter.

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

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

The single parameter 'window' is fully described in the schema (enum, description explaining trade-offs). The tool description echoes this but adds little incremental value, hence baseline score for 100% schema coverage.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a specified window. It distinguishes itself from siblings like discover_tools and search by focusing on popularity trends rather than tool discovery or general search.

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 lists three explicit use cases for the tool (discovering hot data sources, confirming canonical tool, aligning use case). While it doesn't explicitly state when not to use it, the use cases provide clear context for appropriate application.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe, non-modifying analysis. The description adds extensive behavioral detail: monotonicity checks, partition_sum validation, semantic anchor with Jaccard similarity, placeholder filtering, fill_check that warns against trading when realizable edge is non-positive. 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 starts with the core purpose, then details each mode, followed by technical filters and response structure. Every sentence adds value, though it could be slightly more concise for very rapid parsing. Nonetheless, it is clearly organized and front-loaded with essential 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 absence of an output schema, the description thoroughly explains the response structure (opportunities[], partition_check, fill_check) and edge cases (skipped_low_similarity, placeholders). It covers all necessary context for an AI agent to understand inputs, behavior, and outputs, 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?

Input schema has 100% description coverage with brief descriptions for event and topic. The tool description greatly enriches this by providing example slugs, explaining the mechanics of each mode, and noting that full URLs are accepted. The description fully compensates for any lack of detail in the schema, making parameters crystal clear.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It specifies three modes of operation (no args, event, topic) and distinguishes between them, making it easy to understand what the tool does and how it differs from siblings like polymarket_edges and polymarket_fill_risk.

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: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It explains the rationale for each mode, recommends event for specific markets, and even suggests an alternative tool (polymarket_fill_risk) for custom sizing. This leaves no ambiguity.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds extensive behavioral details: caching policy (1h), response structure (by_segment with three models), edge calculation specifics (slippage, Kelly, 24h-move warning), and diagnostics. 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 thorough but overly long and dense. It front-loads the purpose but includes extensive technical model details that could be more concise. While informative, it lacks 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?

Given the tool's complexity (9 parameters, three model families, no output schema), the description is remarkably complete. It explains the response structure, model logic, tradeable-edge knobs, and diagnostics, enabling correct use without an output schema.

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

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

Schema coverage is 100%, and the description adds meaningful context for many parameters. For example, it explains why min_kelly skips small opportunities, details slippage_pp rationale, and clarifies min_partition_leg_kelly's role. Some parameters like limit and window have sufficient schema descriptions, but overall the description adds 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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for the 'what should I bet on today' use case. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on edge detection across multiple model families.

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

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

The description provides a clear use case for agents discovering opportunities without paging hundreds of markets. It implicitly guides when to use but does not explicitly state when not to use or compare to alternatives, though sibling tools exist.

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, destructiveHint=false. The description adds significant behavioral context beyond these: history depth bounded by 60-day TTL, decay numbers from daily closes not intraday, snapshot timing (written on cache-miss, gaps mean nobody scanned), and details on response structure (tracked, expired, snapshot_dates). 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 concise for the amount of information it conveys. It is front-loaded with the core purpose, followed by a clarifying question, response structure, and limits. Every sentence adds value without redundancy. Could be slightly more compact, 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 the tool's complexity (2 parameters, no output schema, but detailed behavioral needs), the description is complete. It covers what the tool returns (tracked, expired, snapshot_dates), how data is computed (edge_pp_net time-series), and important caveats (TTL, snapshot availability). Annotations cover safety and idempotency. No output schema is needed because the description explains the response 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?

The input schema provides descriptions for both parameters ('days' and 'window') with 100% coverage. The description adds value by specifying defaults (14 for days, '1wk' for window), valid ranges (clamp 2-30 for days), and enumerating window families (24hr, 1wk, 1mo). This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It specifies the resource (edges from snapshots) and verb (track persistence/decay). It differentiates from siblings like polymarket_edges (current edges) and bet_research (bets) by focusing on historical edge behavior and time-series data.

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

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

The description implies when to use: when evaluating how long an edge has existed and whether it's decaying. The example contrasting a fresh wide edge vs. a 3-week-old wide edge provides context for usage. However, it does not explicitly name alternative tools or state when not to use this tool, though the sibling list implies alternatives are available.

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 behavioral details: walks the ladder, returns specific fields, warns about forced directional risk and thin legs in basket mode. 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 well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET) and front-loads the purpose. While lengthy, the complexity justifies it. Could be slightly more concise, but highly informative with no 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 lacking an output schema, the description thoroughly covers return fields for both modes, edge cases (thin books, partial fills, directional risk), and ties to sibling tools. 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), but the description significantly adds meaning: explains different interpretations of size_usd for single-market vs basket, side defaults and meanings, and clamp range. This goes well 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's purpose as a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It lists specific return fields and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround not capturable, partial fills cause directional risk) and provides conditional requirements (one of market or event).

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

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

Adds rich behavioral context beyond annotations: explains compatibility_warning conditions, temporal_alignment, skipped cross types. Annotations already declare readOnly, openWorld, idempotent, non-destructive; description expands on edge cases and safety fields.

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

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

Packed with valuable info, front-loaded with core purpose, then modes, response, safety fields, warnings. Could be slightly tightened but every sentence earns its place.

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

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

No output schema, but description compensates by explaining response structure (leg-by-leg prices, top_spreads_pp, safety fields). Covers temporal alignment, skipped counters, and warning scenarios. Complete for a comparison tool.

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

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

Schema coverage is 100% with concise descriptions. Tool description enriches by explaining modes, topic shortcuts, and explicit override behavior, adding meaning beyond bare schema.

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

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

Clearly states the tool computes cross-venue spread between Kalshi and Polymarket. Specific verb+resource, distinguishes from siblings (polymarket_arbitrage, polymarket_edges).

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

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

Provides clear context for two modes (topic and explicit), explains compatibility warnings and when spreads are meaningful. Lacks explicit 'when not to use' or alternative tools, but covers usage well.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds scoping details (anonymous IP, BYO key hash, account ID) and pairing with remember/forget, which is valuable behavioral context beyond annotations.

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

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

Three sentences, front-loaded with purpose, no redundant words. Every sentence earns its place, providing purpose, usage, and context efficiently.

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?

Though no output schema, the description explains return behavior (value or list of keys). It could specify format or examples, but for a simple retrieval tool, it is fairly complete. Also mentions pairing with remember/forget for full 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 coverage is 100% with a 'key' parameter. The description adds meaning by explaining that omitting key lists all keys, which the schema does not explicitly convey. This enhances usability.

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 keys if omitted. It specifies the verb (retrieve/list) and the resource (saved values/keys), and distinguishes from siblings like 'remember' and 'forget'.

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

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

The description explains when to use: 'to look up context the agent stored earlier' and notes scoping. It does not explicitly state when not to use, but provides clear context for usage.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds that mark_read:true flags events as read for future calls, that polls work fine, and specifies 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?

Five sentences with front-loaded purpose. Each sentence adds value without unnecessary fluff. Could be slightly more concise but is 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 no output schema, the description adequately describes return format (source, citation_uri, payload). It also mentions polling and an alternative endpoint. Parameter count and behavior are well covered.

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%. The description adds context beyond schema by providing an example filter value (sec_8k), noting ISO format for since, and explaining the effect of mark_read. This adds meaningful usage hints.

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 pulls fired events from the subscription feed and returns recent alerts with specific fields. It is specific about the resource and action, but does not explicitly distinguish from sibling tools.

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

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

The description provides guidance on filtering by type, since, and setting mark_read, but does not state when to use this tool vs alternatives or when not to use it. The mention of an alternative HTTP endpoint is helpful but not for 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 declare safety (read-only, idempotent). Description adds multi-source fan-out, fallback logic (GDELT→GNews), USPTO soft-fail, and structured return format – significant added value.

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?

One efficient paragraph with front-loaded intent. Every sentence adds value, though could be even more scannable with bullet points.

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

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

Covers key aspects (sources, fallback, USPTO status, return structure) but omits result limits or pagination. Acceptable for a tool without output schema.

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

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

Schema coverage is 100%; description adds concrete examples for 'since' (e.g., "7d", "30d"), clarifies type restriction (only company), and explains value formats (ticker or CIK), going 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 uses concrete example queries ("What's new with X", "latest on Y") and explicitly distinguishes from sibling tool entity_profile, making the purpose unmistakable.

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

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

Provides clear context when to use (for change feeds) and explicitly names entity_profile as alternative for static profile, but does not list other exclusions.

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

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

Annotations indicate idempotent and non-destructive. Description adds scoping by identifier, persistent vs temporary storage, and pairing with recall/forget. 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 medium length, front-loaded with main purpose, and each sentence adds value. Slightly verbose 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?

For a tool with 2 parameters and no output schema, the description fully covers purpose, usage, behavior, and examples. Sufficient for an AI agent to understand 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 descriptions for key and value. Description provides examples and context but does not add significant meaning beyond the schema. Baseline 3 applies.

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

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

The description clearly states the tool saves data for reuse across conversations/sessions, provides specific examples like tickers and addresses, and differentiates from siblings recall and forget.

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

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

Explicitly advises use when discovering something worth carrying forward and pairs with recall/forget. Retention differences for authenticated vs anonymous are noted. No explicit when-not, 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 read-only, idempotent, non-destructive, open-world. Description adds that each call cascades through several endpoints internally, replacing multiple manual lookups, and specifies return fields per type (e.g., ticker + CIK + citation URI). 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?

Front-loaded with user-friendly examples and a clear directive. Each sentence serves a purpose: examples, usage guidance, supported types with details. No fluff.

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

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

Given no output schema, the description adequately explains return values for both entity types, including citation URIs. It covers the lookup behavior and use cases fully, making it self-contained for agent decision-making.

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

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

Schema covers 100% of parameters with descriptions. Description enriches by providing concrete examples (ticker, CIK, name for company; brand/generic for drug) and noting auto-disambiguation for company input. Adds meaning 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?

Description clearly states the tool resolves names to canonical identifiers, with specific examples like ticker, CIK, RxCUI. It distinguishes from sibling tools by positioning itself as the first step when a name is known but an ID is needed, replacing 2-3 manual lookups.

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 to 'Use FIRST whenever you have a name but need an ID' provides clear context. Though it doesn't explicitly exclude cases where IDs are already known, the directive is strong enough. It does not compare to siblings like search or ask_pipeworx, but the coverage is adequate.

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

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

Annotations already provide readOnlyHint and idempotentHint. Description adds that it probes each entity with ai_visibility_check internally, returns ranked list with score, confidence, signal density. No contradictions. Auth requirements for Anthropic model mentioned. Reasonable 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?

Two short sentences: first explains action and methodology, second adds use case and return format. No fluff, front-loaded. Every sentence earns its place.

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

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

Tool has 4 parameters, no output schema. Description explains return format (ranked list with score, confidence, signal density) and mentions model options and auth. Missing details on ranking algorithm but adequate for usage.

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. Description adds one nuance: first entity treated as subject. Otherwise, no new parameter details. Baseline 3 as per rules when schema is comprehensive.

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 tool compares AI visibility across entities side-by-side, probes with ai_visibility_check, ranks by score. Distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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 concrete use case: competitive AI-marketing audits. Implies usage for comparing multiple entities vs single. Could be more explicit about when not to use but context is clear. Sibling differentiation is present.

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, non-destructive behavior. The description adds key behavioral details: fan-out across multiple services, bundlephobia's first measurement can take 5-30s, partial failures degrade gracefully with 'sources_failed' list. 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 efficiently front-loaded with the core purpose and quickly expands on behavior, return values, and limitations. While it covers necessary details, it is slightly long (5-6 sentences) but each sentence earns its place. Minor trim possible.

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 lists all return fields (summary block with fields, per-advisory details, links, alternative versions) and explains partial failure behavior. For a complex multi-source tool, this is thorough and complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds that scoped packages like '@types/node' are accepted and that version defaults to latest, but does not significantly enhance understanding beyond schema. Adequate.

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: a composite check for npm packages covering deps.dev and bundlephobia. It specifies the exact verb (check if 'should I add') and resource (npm package for a project), and distinguishes from siblings by limiting scope to NPM ecosystem, fact that other ecosystems use 'deps.dev:version directly'.

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 when to use: when an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also states when not to use: only NPM packages, and alternatives for PyPI/Maven/Cargo/Go fall under deps.dev. Partial failure behavior is also described.

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 false, covering safety and idempotence. The description adds context about the search scope (biomedical knowledge graph, entity types) and pagination behavior, which is valuable 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?

A single concise sentence that front-loads the main purpose (full-text search) and efficiently incorporates all key details (knowledge graph, entity types, filter, pagination). No wasted words.

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

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

Given the moderate complexity (4 parameters, output schema exists), the description covers the tool's purpose, supported entity types, filtering, and pagination. The output schema handles return values, so the description is sufficiently complete.

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

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

Schema description coverage is 50% (limit and category have descriptions, query and offset do not). The description explains how limit/offset enable pagination and how category filters results, compensating for the missing schema descriptions and providing usage context for all parameters.

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

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

The description clearly states it performs full-text search across the Monarch biomedical knowledge graph for specific entity types (diseases, genes, phenotypes, etc.), with filtering and pagination. This verb+resource combination distinguishes it from sibling tools like 'search_within' or 'entity'.

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 searching the Monarch knowledge graph but does not explicitly state when to use this tool over alternatives like 'search_within' or 'resolve_entity'. No exclusions or comparative guidance is provided.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds details about return format (passages with offsets and scores), context saving, and truncation behavior (200K caps with flag).

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?

Concise (~100 words), front-loaded with main purpose, followed by technical details and pairing suggestion. Every sentence adds value; no redundancy.

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

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

For a complex tool with no output schema, description covers return format (top-N passages, offsets, scores), technical constraints (200K chars, embedding model), and provides enough detail for an agent to correctly invoke and interpret results.

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

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

Schema coverage is 100%, but description enriches by explaining 'text' as a previously fetched document, 'query' as natural language with examples, and 'limit' range and default. Adds practical context not in 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?

Explicitly states 'semantic search inside a fetched record', specifies verb and resource, distinguishes from siblings like 'search' and 'ask_pipeworx_grounded', and provides mechanics (BGE-base-en, cosine, windows).

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?

Clearly states when to use (when record is too big for prompt) and pairs with an alternative tool (ask_pipeworx_grounded). Gives example queries but lacks explicit 'do not use when' conditions.

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

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

Beyond annotations (readOnlyHint false, idempotentHint true, destructiveHint false), the description adds significant behavioral context: OAuth requirement, type constraints, SMS cap (10/day), webhook auto-disable after 10 failures, and that webhook secret is returned once. 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 a single dense paragraph, front-loaded with purpose. Every sentence adds value, but it could benefit from clearer structuring (e.g., breaking out types or delivery options) for easier scanning.

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 (one nested), no output schema, and complexity, the description covers input thoroughly and mentions the output (new subscription id) plus the webhook secret once. It misses explicit description of the full response object, but the output is likely minimal. Overall fairly 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 greatly enriches parameter understanding: each type's params are detailed with examples, and the delivery object is explained with caveats (phone verification, webhook signing). The description adds substantial value beyond the schema.

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

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

The description clearly states the verb-resource pair: 'Create a proactive monitoring subscription'. It distinguishes from siblings like list_subscriptions, recent_alerts, and unsubscribe by specifying the creation action and returning a new subscription 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?

The description provides usage context: requires a Pipeworx OAuth account, lists supported types with examples, and describes delivery channels. However, it does not explicitly state when not to use or compare with alternatives, though sibling tools imply the niche.

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

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

Annotations already cover readOnly, idempotent, openWorld, non-destructive. Description adds that it returns 'exact tool + argument shape' and 'drawn from live catalog'. No contradictions. Additional context beyond annotations.

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

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

Description is slightly long but well-structured with examples in parentheses. Front-loaded with common user queries. Every sentence contributes value; could be slightly tighter 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?

No output schema, but description explains return format (category-bucketed example questions with tool+argument shapes). Covers purpose, usage, and output in sufficient detail. 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 has 100% coverage (topic optional with description). Description adds meaning: 'Omit for a cross-category spread' and lists valid topics. Enhances understanding beyond schema.

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

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

Description clearly states it is the onboarding entry point, returning category-bucketed example questions. Uses specific verbs like 'returns category-bucketed example questions' and distinguishes from siblings like 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?

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do' and mentions alternatives like meta-tools (ask_pipeworx, entity_profile). Also advises on arguments (omit for full spread, pass topic to focus).

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

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

Annotations provide idempotentHint and openWorldHint but no destructiveHint. The description adds critical behavioral details: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This goes beyond annotations and clarifies side effects.

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

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

Two sentences with no filler. The first sentence front-loads the action; the second adds constraints and behavior. Every sentence is meaningful.

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 parameter and no output schema, the description covers purpose, ownership constraint, and side effects. No gaps remain.

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 value by specifying that the 'id' is 'returned by subscribe,' guiding the agent on where to obtain this parameter.

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 'Cancel a subscription by id,' which is a specific verb and resource. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by being the inverse operation.

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

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

The description mentions ownership enforcement ('only cancel your own subscriptions'), providing a key usage constraint. It does not explicitly list alternatives but the context implies when to use versus 'subscribe'.

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, idempotentHint, destructiveHint false, and openWorldHint. The description adds substantive behavioral context: data sources (SEC EDGAR + XBRL), return format (verdict, structured form, actual value with citation, percent delta), and efficiency gains (replaces 4-6 sequential calls). 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, front-loaded with usage patterns, and each part adds value. It is slightly verbose but efficient for the amount of information conveyed.

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

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

Given the single parameter, rich annotations, and no output schema, the description completely covers the tool's domain, behavior, return values, and data sources. No gaps are apparent.

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

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

Schema coverage is 100%, baseline is 3. The description adds meaning by specifying the domain (company-financial claims) and providing examples of valid claims, which aids the agent in formulating the parameter correctly.

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: verifying natural-language claims against authoritative sources, specifically company-financial claims for public US companies. It includes example natural language patterns and distinguishes from siblings by noting it replaces multiple 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 scopes the domain to company-financial claims. No explicit exclusions or alternatives are given, but the context makes the usage clear.

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