Idigbio

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint. Description adds: default model selection, need for _apiKey for Anthropic probes, score range 0-100, and return structure (per-model + combined). No contradictions with annotations.

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

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

Two sentences, front-loaded with main action and output. No wasted words, covers purpose, behavior, and use cases 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?

With 4 parameters fully described, missing output schema compensated by description of return structure. Annotations provide safety profile. Sibling tools do not overlap significantly. Description is sufficient for effective 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?

All parameters have schema descriptions (100% coverage). Description enriches semantics: explains scoring, default model, that _apiKey bypasses standard billing, and context helps disambiguate. Adds value beyond schema.

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

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

Description states specific verb 'probe' and resource 'LLMs for visibility of an entity', with scoring scale. Clearly distinguishes from sibling tools like ask_pipeworx or bet_research by focusing on brand/product visibility across multiple LLMs.

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 suggests use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' Implicitly guides when to use by contrasting free default model and BYO key option. Lacks explicit when-not or direct comparison to alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond that: it routes to other tools, fills arguments, returns pipeworx:// citation URIs, works on every tier, and is 'one fast call'. No contradiction with annotations. Minor gaps like rate limits or failure behavior are not mentioned, but the added context is substantial.

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

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

The description is long (~250 words) but densely packed with valuable information and logically structured: directive first, then capabilities, triggers, examples, and alternatives. Every sentence earns its place, though it could be slightly trimmed without losing meaning. The front-loaded 'PREFER OVER WEB SEARCH' sets immediate context.

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 (a meta-router with thousands of sources), the description covers its function, when to use it, what to pass, and alternatives. It does not define the return structure beyond 'structured answer with citation URIs', but since no output schema exists, some return-format detail would help. Overall it is sufficiently complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% (all 6 params are documented aliases for 'question'), so baseline is 3. The description significantly enhances parameter semantics by providing a rich set of trigger phrases and example questions ('current US unemployment rate', 'Apple's latest 10-K'), which helps the agent formulate the question parameter correctly. This goes beyond schema descriptions that merely list aliases.

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 routes questions to 5,529 tools across 1455 verified sources, fills arguments, and returns structured answers with citations. It uses a specific verb ('routes') and resource, and explicitly contrasts with sibling tools like ask_pipeworx_grounded and deep_research, making its unique 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?

Extensive when-to-use guidance is provided: 'PREFER OVER WEB SEARCH' lists specific triggers ('what is', 'look up', 'find'), and gives concrete examples. It explicitly states when to step up to alternatives ('for hallucination-resistant... use ask_pipeworx_grounded; for broad/multi-part... use deep_research'), and even covers breaking-news handling. This is exemplary usage 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?

The description goes beyond annotations by revealing the experimental nature, the current lack of an active candidate, and the fact that results are compared for merge decisions. It also clarifies that it falls back to nothing—it's a full working router, not a stub.

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 compact with three sentences, front-loading the beta status and immediately clarifying the relationship to ask_pipeworx. No filler.

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

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

Given the absence of an output schema, the description covers the tool's identity, usage, current state, and behavior. It even notes the response shape matches ask_pipeworx. This is sufficiently complete.

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

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

Schema coverage is 100% with all parameters documented as aliases. The description only references 'same arguments' without adding new semantic detail, so baseline 3 is appropriate.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same 5,529 tools and arguments. It distinguishes itself from the stable ask_pipeworx by its experimental edge, making its 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?

It explicitly instructs to use it like ask_pipeworx when wanting the newest routing, and notes current equivalence to the stable router. This provides clear when-to-use guidance, though it doesn't discuss alternative ask_pipeworx_grounded.

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/idempotent/openWorld, and the description goes far beyond by detailing the internal routing, extraction-from-results-only constraint, and the full refusal reason enum. It also discloses the cost implication (extra LLM call), adding rich behavioral context not available from annotations or schema.

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?

Although the description is long, every sentence provides distinct value: purpose, routing pipeline, return structure, failure modes, usage context, and cost trade-off. It front-loads the core purpose and logically organizes details, earning its length without bloat.

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

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

With no output schema, the description compensates fully by specifying both success payload fields and all refusal reason variants. It also explains the tool's broader routing context and performance trade-off, making it self-sufficient for an agent to grok the complete behavior.

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

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

Schema coverage is 100% with clear descriptions for all six parameters (aliases for 'question'), so the schema carries the full burden. The description adds no extra parameter-specific detail, which is acceptable at the baseline for high coverage but not enhanced.

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

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

The description opens with a specific, verb-first statement: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes this tool from its sibling ask_pipeworx by highlighting the grounded extraction process and explicit evidence/refusal output, making its unique role 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?

Usage is explicitly scoped: 'Use whenever an answer will be quoted, cited, or acted on...' and the description even names the preferred alternative for casual lookups ('prefer ask_pipeworx for casual lookups'). It also informs about the extra LLM call cost, enabling informed 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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds extensive behavioral details: fan-out logic, classifiers, resolver contract (match confidence, alternatives, suggestions), parent event extractor, news fallback fields, safety short-circuits for low-confidence matches and closed markets, wide-spread tradeability warnings, and cancellation rule parsing. This fully discloses the tool's behavior beyond annotations.

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

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

The description is very long (over 600 words) and lacks formatting like bullet points or sections. It is front-loaded with a clear first sentence but contains redundant and overly detailed explanations. Brevity would improve usability for an agent scanning for key information.

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

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

Given the tool's complexity (3 parameters, 100% schema coverage, no output schema, informative annotations), the description is thorough. It covers edge cases (low-confidence matches, closed markets, wide spreads), resolution rules, parent events, and news fallbacks. All critical behaviors for correct usage are documented.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds value by explaining the market parameter input formats (slug, URL, question), depth parameter options (quick vs thorough), and include_raw parameter impact on response size. This contextual information helps an agent choose appropriate parameter values.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types and output components. While very clear, it does not explicitly distinguish from sibling tools like polymarket_edges or polymarket_arbitrage, which could cause confusion for an agent.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear usage context. However, it does not mention when NOT to use this tool or list alternatives, leaving room for improvement.

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 and idempotent, so the description adds valuable context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. It does not mention rate limits or data freshness delays, but overall adds meaningful behavioral traits.

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

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

The description is concise despite its length, front-loaded with natural language examples and then structured details. Every sentence adds unique information: triggers, data sources, type-specific behavior, sorting, and efficiency gains. No filler.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description covers all essential aspects: what data is returned (paired data + citation URIs), how results are sorted, and the entities it supports. It is sufficiently complete 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%, but the description greatly enriches parameter semantics: it explains what each type returns (company: latest 10-K metrics; drug: FAERS counts, FDA approvals, trials) and gives explicit examples for values (tickers/CIKs for company, drug names). This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It uses specific verbs and resources (compare entities, pulls financial data, adverse-event counts). It distinguishes itself from siblings by explicitly recommending over sequential single-pack lookups and noting it replaces many 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?

The description provides explicit when-to-use guidance with natural language triggers (e.g., 'compare X and Y', 'which is bigger'). It strongly recommends this tool over sequential lookups for comparisons, implying when not to use (when not comparing multiple entities). This is clear and actionable.

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 safe, non-destructive behavior (readOnlyHint, idempotentHint, destructiveHint=false). The description adds the context 'Keyless', suggesting no API key required, and specifies that scoping is optional. No contradictions with annotations.

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

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

Two sentences efficiently convey purpose, scope, and key feature (optional filters). No wasted words; front-loaded with the core action.

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 count tool with good annotations, the description covers the main functionality. It mentions 'top values + counts', matching the top_count parameter. However, it does not describe the return format (e.g., JSON structure), which would improve 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?

Schema coverage is 100% with all parameters described. The description adds no new parameter details beyond restating the grouping field and optional filters, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Get', the resource 'taxonomic/geographic specimen counts grouped by a field', and the scope 'across iDigBio'. It distinguishes itself from sibling tools like 'search_specimens' by focusing on counts rather than specimen records.

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 optional filters but does not explicitly guide when to use this tool versus alternatives. It implies usage for aggregated counts, but lacks explicit when-to-use or when-not-to-use guidance.

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

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

Annotations only indicate readOnly/openWorld/idempotent/non-destructive. The description adds account requirements, parallel execution across 5,529 tools, return packet shape (evidence, confidence, source, citations, gaps[]), depth-specific behaviors (gap recovery, contradiction scans, extra hop), semantic excerpting, and latency expectations. All disclosures align 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?

Long but every sentence earns its place; front-loaded with account restriction and alternative tool, then scope, use cases, depth mechanics, citation details, and latency. Structured in logical paragraphs, 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?

For a complex tool with no output schema, the description covers prerequisites, input semantics, return value structure (findings packet, gaps[], contradictions[], citation_uri), edge cases (current-news topics yield empty gaps), and performance characteristics. Nothing critical is missing.

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

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

Both parameters are already in the schema (100% coverage), but the description enriches them: depth:'thorough' requires a paid plan, depth:'standard' adds gap-recovery and contradictions[], and question format accepts broad/multi-part queries. Also gives latency per depth, which helps the agent set expectations.

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?

States a clear verb ('research') and resource ('Pipeworx's 1455 STRUCTURED data sources') and explicitly distinguishes from open-web search and ask_pipeworx, with examples like 'compare X and Y's regulatory + financial exposure'. This leaves no ambiguity about the tool's function.

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

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

Provides explicit when/when-not guidance: 'Best for broad/multi-part questions', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. Names the alternative tools directly.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about what the tool returns (top-N relevant tools with schemas) and that results are 'ready to call directly.' No contradictions; description adds moderate value beyond annotations.

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

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

The description is information-dense without redundancy. It starts with the core action, lists domains, explains output, and ends with usage guidance. Every sentence serves a purpose and 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?

Despite no output schema, the description details what the tool returns (names, descriptions, schemas). It addresses the 6 parameters (mostly aliases) and provides examples. The tool's behavior is fully described for its discovery role.

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

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

Schema coverage is 100% with descriptions for all parameters. The description reinforces that query accepts natural language and gives examples. It also clarifies that multiple aliases are accepted, adding 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?

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many example domains and explains that it returns tool names, descriptions, and full input schemas. This distinguishes it from siblings which are specialized 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 explicitly advises: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance, implying not to use when you already know the specific tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context about parallel fan-out across multiple sources, return fields, and a soft-failure note for the USPTO sunset. No contradictions; adds value by detailing internal behavior.

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

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

The description is information-dense but well-organized: begins with examples, then a clear declarative summary, followed by a bullet-like listing of return components. Each sentence earns its place, though it could be slightly tightened without losing context.

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

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

With no output schema, the description carries full burden of explaining all returned fields (cik, filings, fundamentals, patents, news, LEI) and their formats (pipeworx URIs). It also covers the patent API sunset and fallback behavior. For a complex multi-source tool, this is thoroughly 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 meaningful detail: for 'type', it notes only 'company' is supported; for 'value', it specifies acceptable formats (ticker or zero-padded CIK) and explicitly excludes names. This goes beyond the raw schema.

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

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

The description begins with concrete user queries ('Tell me about X', 'research Acme'), immediately stating the tool's purpose: generating a full cross-source profile of a US public company in a single parallel call. It clearly distinguishes itself from chaining individual lookups and from sibling tools like 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?

Explicitly tells when to use (holistic view) and when not to use (if only have a name, use resolve_entity first). Specifies accepted inputs (ticker or zero-padded CIK) and unsupported inputs (names). Alerts preference over chaining single-pack lookups.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's mention of 'delete' aligns. The description adds context about clearing sensitive data but does not reveal additional behavioral details beyond the annotations.

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

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

The description is concise with two sentences, no wasted words. It is front-loaded with the core action and provides usage guidance 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?

Given the tool's simplicity (one parameter, no output schema), the description is complete: it explains the action, when to use, and how it relates to sibling tools. 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% with a clear description for the 'key' parameter ('Memory key to delete'). The description does not add extra meaning beyond what the schema provides, so a baseline of 3 is appropriate.

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

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

The description clearly states the action ('Delete') and the resource ('previously stored memory by key'). It also distinguishes itself from siblings by mentioning pairing with 'remember' and 'recall'.

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

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

The description explicitly states when to use the tool: when context is stale, task is done, or to clear sensitive data. It also references sibling tools ('Pair with remember and recall'), providing clear usage guidance.

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

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

The description details the process (fetch page, extract title/description/key links, output markdown) and deployment suggestion, significantly enriching beyond the annotations that declare read-only, idempotent, and non-destructive.

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

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

Three sentences, each serving a distinct purpose: main function, process details, use cases. Front-loaded and no redundant information.

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

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

For a simple tool with full schema coverage and annotations, the description adequately explains output format and deployment, with no gaps in 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%, and the description largely restates schema info (url, max_links default/max). No additional semantic value beyond what the schema provides, meeting baseline expectation.

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 generates an llms.txt file for any URL, specifying verb and resource. Among sibling tools, none perform this function, so it is clearly distinguished.

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

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

Use cases are provided (indexing client sites, drafting for own project, auditing competitors), giving clear when-to-use context. However, no explicit exclusions or alternative tool references.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds context that it returns a 'full normalized record' and provides an example, but does not significantly extend 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, no wasted words. First sentence states core purpose. Second provides example and key attribute. Efficient 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?

For a simple retrieval tool with one parameter and no output schema, the description covers purpose, gives an example, and mentions keyless access. It omits return format but annotations provide safety and idempotency info. Reasonably 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 covers the uuid parameter with 100% description coverage. Description adds an example of a uuid and the note 'Keyless', but this does not add substantial meaning beyond the schema for parameter usage.

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

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

Description clearly states 'Get the full normalized record for a single iDigBio specimen by its uuid', providing a specific verb and resource. It distinguishes from sibling tool 'search_specimens' which returns multiple specimens.

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?

Description implies usage for a single specimen by uuid but does not explicitly guide when to use this tool versus alternatives like 'search_specimens'. No exclusions or when-not-to-use guidance 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, destructiveHint, idempotentHint. Description adds the return structure and default scope (active subscriptions), which aligns with annotations.

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

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

Two sentences: first states purpose and outputs, second gives usage guidance. No wasted words, front-loaded 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?

For a simple list tool with one optional parameter and no output schema, the description fully covers purpose, return fields, and usage context.

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

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

Schema coverage is 100% and describes the 'include_inactive' parameter. Description implicitly indicates default (active only) but adds no new parameter details beyond schema.

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

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

Clearly states it lists the caller's active subscriptions and enumerates return fields (id, type, etc.), differentiating from siblings like 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 advises use for reviewing subscriptions before adding more or finding an id to cancel, providing clear context for invocation.

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

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

The annotations only show all false hints, contributing little, so the description carries the transparency burden. It discloses the claim_token flow for follow-up, daily digest reading, the 5-per-day rate limit, and that it's free with no quota impact. These are important operational behaviors an agent needs to know before invoking.

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

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

The description is long but well-structured, with each sentence adding a distinct piece of information: purpose, triggers, exclusion, token mechanics, rate limit, and cost. It's appropriately front-loaded with the core action. While every sentence earns its place, the length is slightly higher than the minimum needed, so a 4 is appropriate.

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

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

With no output schema and minimal annotation information, the description carries the full burden—and it does so thoroughly. It covers what, when, when-not, how (including the token flow), and operational constraints like rate limits and cost. An agent has all the information needed to decide whether and how to use this 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?

The input schema provides 100% coverage of parameter meanings, so the baseline is 3. The description adds valuable nuance: telling users to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts, and demonstrating the claim_token syntax for retrieving earlier feedback results. This goes beyond the schema's field descriptions.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist'—a specific verb and target, immediately clarifying the tool's purpose. It clearly distinguishes itself from sibling tools like ask_pipeworx, discover_tools, and other research-oriented tools by being the dedicated reporting channel for issues with Pipeworx tools.

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

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

Explicitly states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a precise exclusion: feedback about tools from other MCP servers should be filed there, not here. This is clear when/when-not guidance with named alternatives.

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

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

Discloses data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h depending on window). Annotations already cover hint, but description adds 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?

Front-loaded with main purpose, then bulleted uses, then technical details. Every sentence adds value, 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?

Given the simple tool (1 param, no output schema, rich annotations), the description covers purpose, usage, transparency, and parameter semantics completely.

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 single parameter (window) that has enum and description. Description adds nuance: short vs long windows surface different trends, but schema already documents it well.

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

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

The description clearly states it returns top tools, packs, and call volume over a recent window, using specific verbs and resource. It distinguishes from siblings like 'discover_tools' and 'ask_pipeworx' by focusing on what other agents are calling.

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

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

Explicitly lists three use cases with bullet points (discovering hot data, confirming canonical choice, seeing alignment). Does not explicitly state when not to use, 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?

The description adds extensive behavioral details beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It explains monotonicity checks, partition-sum checks, semantic anchor with Jaccard similarity, partition filter with placeholder slugs, fill check against live CLOB depth, and conditions for null signals. 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 long but well-structured, starting with the main purpose then detailing modes, semantics, and response format. Every sentence adds value, though it could be slightly more concise without losing information. It effectively front-loads the key action.

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

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

Despite lacking an output schema, the description fully explains the response structure: opportunities[] with fields (gap_pp, suggested_trade, reasoning, monotonicity violation context) and event-mode partition_check. It also details fill_check outputs. For a complex tool, this is exceptionally 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%, but the description adds significant meaning: for 'event' it explains walking child markets and checking date-axis/threshold-axis ordering; for 'topic' it explains cross-event scanning and structural patterns. It also clarifies that URLs are accepted for event slugs.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It uses specific verbs (find, call, pass) and distinguishes between modes (no args, event, topic), making it distinct from sibling tools like polymarket_edges or 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?

Explicit guidance on when to use each mode: 'Call with NO args for a trending_scan; pass event for the strongest per-event partition_check; topic for cross-event scan.' It also recommends event mode for specific markets, and advises against trading when realizable_edge_pp ≤ 0. It points to polymarket_fill_risk for custom sizing.

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. The description adds substantial context: caching at KV level for 1h, diagnostics to explain empty segments, fed_candidates caveat, and detailed edge computation methodology (e.g., 24h-move warning). This goes well beyond what annotations provide.

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

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

The description is long but well-structured with clear sections (segments, response structure, diagnostics). Every sentence adds detail, but it could be more concise for an AI agent. The front-loading is good with the opening sentence stating core purpose.

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

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

Given the tool's complexity (9 parameters, no output schema, nested objects), the description is exceptionally complete. It explains each segment's methodology, response top-level, diagnostics, caching, and caveats like fed candidates. The rationale for missing fields (e.g., partition leg kelly) is also 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?

All 9 parameters have schema descriptions (100% coverage). The tool description adds value by grouping knobs like 'TRADEABLE-EDGE KNOBS' and explaining their interplay (e.g., min_partition_leg_kelly for partition arbs). This contextualizes parameters beyond standalone 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?

Clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It distinguishes its purpose with 'Built for what should I bet on today' and avoids paging. The three model segments are described, making it very specific and distinct 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 implies use for discovering betting opportunities but does not explicitly state when not to use it or provide alternatives. While siblings exist (e.g., polymarket_arbitrage, polymarket_edge_tracker), no guidance on choosing between them is given.

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. The description adds rich behavioral details: explains response structure (tracked[], expired[], snapshot_dates[]), sign convention for edge_pp_net, and limitations (daily closes, not intraday, bounded by TTL). 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 thorough but somewhat verbose, including detailed response field explanations. It is front-loaded with the purpose, but some details (like sign convention) could be omitted if output schema existed. Still, it remains readable and organized.

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

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

Given no output schema, the description fully covers return values (tracked, expired, snapshot_dates) and handles edge cases like missing data. It provides all necessary behavioral and structural context 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% with both parameters described. The description adds practical context: default values (days=14, window='1wk') and clamp info (days max 30). While not extensive, it enhances understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: to answer 'how long has this edge existed and is it shrinking?' It specifies the verb (track edge persistence and decay) and the resource (daily polymarket_edges snapshots). The tool is distinguished from siblings like polymarket_edges by being a derivative analysis tool.

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

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

The description provides context for when to use (checking edge persistence) and limits (60-day TTL, daily closes). It does not explicitly list when not to use or compare to alternatives, but the purpose is clear enough to guide appropriate use.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds detailed behavioral context: walks the order book ladder, returns verdicts (clean|degraded|cannot_fill), and warns about forced directional risk. 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 dense and structured with bold headers for modes, but it is somewhat lengthy. However, every sentence adds value; minor reduction could improve conciseness 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?

No output schema is provided, but the description thoroughly lists return fields for both modes, including edge cases like thin_legs and forced_directional_risk. It explains the risk of partial basket fills, making the output expectation clear.

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?

All four parameters have 100% schema coverage, but the description adds significant meaning: explains size_usd interpretation for buys vs sells and basket mode (settlement notional), side defaults and auto-detection in basket mode, and market/event distinction. The description provides context 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 tool's purpose as a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by indicating this tool is a prerequisite check.

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 when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale (theoretical overround not capturable on thin books, partial fills converting arb to directional risk).

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

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

Annotations indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds substantial context beyond annotations, including compatibility warnings, temporal alignment fields, and skipped cross-type/subtype counts. No contradiction exists; the description fully discloses behavioral nuances.

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 longer but well-structured: it starts with purpose, then explains modes, response, and safety fields. Every sentence adds value. Could be slightly more concise, but the organization makes it easy to parse.

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 output schema, the description thoroughly explains response structure (leg-by-leg prices, spreads, compatibility warnings), temporal alignment, and skipped counters. Given the tool's complexity, this is complete and leaves no major gaps.

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

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

Schema coverage is 100% for all 3 parameters. The description adds meaning by explaining the topic enum values and the override behavior of explicit tickers/slugs. This goes beyond a baseline of 3 by providing real-world usage context and trade-offs.

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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage by focusing on inter-venue comparison. The verb 'compute' is implied, and the resource is well-defined.

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

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

The description explains two modes (topic and explicit) and when to use each, advises that pre-mapped topics often return compatibility warnings, and details safety fields. It provides clear context but does not explicitly mention alternative tools like polymarket_arbitrage for single-venue arbitrage, which would strengthen 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, idempotentHint, and destructiveHint. Description adds context about listing all keys by omitting argument, scoping, and pairing with remember/forget, exceeding annotation coverage.

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 the main action, every sentence adds value. No redundancy or 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?

Fully covers purpose, usage, scoping, and pairing. No output schema needed, annotations handle safety. Complete for a simple retrieval tool.

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

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

Schema coverage is 100% with a clear description for the key parameter. Description adds usage details and examples, providing additional 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?

The description clearly states the verb (retrieve/list) and resource (saved values/keys). It distinguishes from sibling tools 'remember' and 'forget' by explicitly pairing with them.

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 ('to look up context the agent stored earlier') and when not to ('without re-deriving it from scratch'). Provides examples and notes scoping per identifier.

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

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

Annotations (readOnlyHint, idempotentHint, openWorldHint, destructiveHint false) already indicate safe, read-only behavior. The description adds critical context: mark_read affects future calls, polling works fine, and events carry specific fields. 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?

Four sentences, front-loaded with purpose, no redundancy. Every sentence adds new information (purpose, fields, filters, mark_read behavior, alternative access). Highly 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 read-only, non-destructive tool with no output schema, the description adequately explains return fields, filtering, state management, and alternative access. No gaps identified given the tool's simplicity.

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 value beyond schema by providing example type ('sec_8k'), clarifying mark_read's effect on subsequent calls, and emphasizing ISO timestamp format for since. Slight room for more parameter elaboration (e.g., limit range mentioned in schema but not description).

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

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

The description starts with 'Pull fired events from your subscription feed,' clearly stating the action and resource. It specifies returned fields (source, citation_uri, raw payload) and distinguishes from sibling tools like list_subscriptions (subscription management vs. event 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?

Explicit guidance on filtering by type and since, setting mark_read to manage read state, and noting that the same feed is available via HTTP for scripts/dashboards. This provides clear when-to-use and 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, idempotentHint, and openWorldHint. The description adds useful behavioral details: fans out in one parallel call, fallback from GDELT to GNews, USPTO soft-fail until May 2025, and return structure with grouped changes and citations.

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 well-structured, starting with example queries, then sources, parameter hints, and sibling comparison. It is slightly verbose but every sentence contributes necessary detail, earning 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?

Given no output schema, the description explains the return format (changes[], total_changes, citation URIs) and covers multiple data sources with fallback behavior. It is fairly complete for a complex aggregation tool, though it omits mention of pagination or date range limits.

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

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

Schema coverage is 100%, so baseline 3. The description adds value by explaining the 'since' parameter accepts ISO dates and relative shorthand with examples (e.g., '7d', '3m'), and clarifies 'value' can be ticker or CIK. It also recommends typical values for monitoring.

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

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

The description clearly states the tool provides a change feed for a company over a recent time window, listing specific data sources (SEC EDGAR, GDELT→GNews, USPTO). It distinguishes from the sibling tool 'entity_profile' by noting entity_profile is for static profiles without a time window.

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 example queries like 'what's new with X' and explicitly recommends using 'entity_profile' for static profiles, giving clear context for when to use this tool. However, it does not exhaustively list when not to use it versus other tools like 'deep_research'.

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 (idempotentHint, etc.), description adds valuable behavioral context: scoped by identifier, 24-hour retention for anonymous sessions, persistent for authenticated users. 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?

Three sentences with front-loaded purpose, followed by usage and behavioral details. Every sentence adds value; 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?

For a simple key-value write tool with 2 parameters and no output schema, the description covers purpose, usage, storage model, and persistence. Paired sibling tools are mentioned, making the context 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% and already provides examples. The description reinforces but does not add meaningful new information beyond what the schema offers. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It provides specific examples (resolved ticker, target address, etc.) and distinguishes from sibling tools by naming 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 says when to use: 'when you discover something worth carrying forward.' Also gives guidance on pairing with recall and forget, and describes persistence differences (authenticated vs anonymous sessions), providing clear context for 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 indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds operational context beyond that: it discloses that resolution cascades through multiple endpoints, degrades gracefully if GLEIF/OpenFIGI are unavailable, and explicitly lists unresolved identifiers rather than omitting them. This is valuable behavioral transparency beyond the safety profile.

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

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

The description is front-loaded with relatable example queries, then structured into 'SUPPORTED TYPES' with clear subsections. It is somewhat long and dense, but every sentence carries useful content—no filler. The structure aids scanning despite the length.

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

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

Given there is no output schema, the description must explain return values, and it does: it details the specific identifiers returned for each type (CIK, ticker, LEI, FIGI with source labels; RxCUI, ingredient, brand, citation) and explicitly addresses failure modes (unresolved list, graceful degradation). This makes the tool's behavior fully predictable.

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 already provides 100% parameter descriptions with examples (ticker, CIK, name; brand/generic drug). The description enriches this by explaining what each type returns (e.g., company returns CIK/ticker/LEI/FIGI with source labels; drug returns RxCUI/ingredient/brand/citation), which adds meaning beyond the raw schema.

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

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

The description explicitly states the tool resolves user-spoken names to canonical/official identifiers needed by other tools. It lists concrete example queries (ticker, CIK, LEI, RxCUI) and clearly differentiates from siblings by positioning itself as the first step when an ID is needed, not a profiling or comparison tool.

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 clear guidance: 'Use FIRST whenever you have a name but need an ID.' It enumerates supported types and input formats, and notes that it replaces 2-3 manual lookups. However, it does not explicitly mention when not to use it or name alternative sibling tools, so it stops short of full when/when-not 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, idempotentHint, openWorldHint, and destructiveHint=false, but the description adds transparency by explaining internal mechanism (calls ai_visibility_check), ranking logic, and output fields (score, confidence, signal density). No contradictions.

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

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

Three sentences: first states purpose, second explains mechanism, third gives example use case. Every sentence is essential and front-loaded. 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?

The description covers purpose, behavior, parameters, and output (ranked list with score/confidence/signal density). Despite no output schema, it fully describes return structure. For a read-only comparison tool with 4 parameters, this is 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 minimal extra semantics: it notes the first entity is treated as 'subject' and context disambiguates names, but this is already implied by the parameter descriptions. No major value added beyond schema.

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

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

The description clearly states it compares AI visibility across multiple entities, ranks them, and surfaces which is most/least recognized. It uses specific verbs like 'probes', 'ranks', 'surfaces' and distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (generic).

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

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

The description provides a concrete use case (competitive AI-marketing audits) and implicitly distinguishes from ai_visibility_check by focusing on multiple entities. However, it lacks explicit when-not-to-use guidance or comparison to other sibling tools like compare_entities.

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

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

The description adds significant behavioral context beyond the annotations: it explains fan-out to two external services, mentions potential slow first measurement for bundlephobia (5-30s) and graceful degradation via 'sources_failed'. This is especially valuable as the agent needs to set expectations for latency and partial results.

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-loading the core purpose and then detailing components. It is relatively concise for the amount of information (purpose, components, usage, ecosystem, edge cases). A slight improvement could be using bullet points for the return fields, but it remains 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?

Despite no output schema, the description enumerates all return fields (summary block fields, per-advisory, links, alternative versions) and covers edge cases (partial failures, timeout behavior). It also clarifies ecosystem limitations and boundaries, making the tool self-contained for the agent.

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

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

Schema coverage is 100% with detailed descriptions for both parameters. The description adds minor extra context (e.g., 'Scoped packages are accepted') but does not substantially enhance the parameter understanding beyond the input schema. Baseline of 3 is appropriate given high 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 it is a composite check for adding an npm package, specifying it fans out across deps.dev and bundlephobia. It directly addresses the user's question 'should I add this npm package', which distinguishes it from sister tools like 'scan_competitor_ai_presence' or 'validate_claim'.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also limits scope to 'NPM ecosystem only in v1' and mentions alternatives for other ecosystems, helping the agent decide when not to use this tool.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive hints. The description adds context: it is keyless (no auth), searches a large dataset (~150M), and requires at least one filter. 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?

Two sentences with high information density: first sentence covers purpose and scope, second covers filters and constraint. No wasted words, well front-loaded.

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

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

For a search tool with no output schema, the description covers key behaviors: data source, size, required filters, and keyless access. Lacks details on pagination beyond limit, but examples in schema help. Minor gap prevents a 5.

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

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

Schema coverage is 100% with clear descriptions for each parameter. The description groups parameters into taxonomy and locality categories, adding slight semantic value, but mostly reiterates filtering capability. Baseline 3 is appropriate.

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

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

The description clearly states the tool searches ~150M natural-history museum specimen records from US collections via iDigBio, using a specific verb ('Search') and resource. It distinguishes from sibling tools like 'get_specimen' by focusing on multiple records and taxonomic/locality filtering.

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 requires at least one filter, guiding appropriate usage. It implies use for filtered batch queries but does not explicitly state when not to use or name alternatives, though siblings provide clear contrast.

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 the tool as read-only, open-world, idempotent, and non-destructive. The description adds significant behavioral details: internal algorithm (BGE-base-en embeddings + cosine), window size (500-char overlapping), and a character cap (200K chars) with truncation behavior. No contradiction exists.

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 four sentences, each serving a distinct purpose: core action, usage context, pairing suggestion, and technical detail. No wasted words; the structure is logical and front-loaded with the most important 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 lacking an output schema, the description adequately covers return values (top-N passages with offsets and scores). It explains internal algorithm, limits, and pairs well with sibling tools. For a 3-parameter tool, it provides all necessary context for an agent to use it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by providing examples for the query parameter ('e.g. supply-chain risk, fiscal year 2024 revenue') and explaining the text parameter's truncation behavior. This exceeds the baseline but doesn't add entirely new information 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 tool's purpose: 'Semantic search INSIDE a fetched record.' It uses strong verbs and provides concrete examples (SEC 10-K, article, long tool result), effectively differentiating it from siblings like 'ask_pipeworx_grounded'.

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

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

The description explicitly states when to use the tool: 'Use when the record is too big to cram into the prompt.' It highlights the benefit of saving context and mentions pairing with another tool. However, it lacks explicit 'when not to use' guidance, which would strengthen the score.

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 details beyond annotations: OAuth requirement, subscription ID return, type-specific filters, delivery channels, SMS cap, webhook signing and auto-disable. Annotations state idempotentHint=true, destructiveHint=false, which align. 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?

Single paragraph that is dense but well-organized: purpose, requirement, types, delivery options. Every sentence adds unique information. No filler or repetition. Front-loaded with key action and return 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?

For a 3-param tool with no output schema, description covers: return type (subscription id), all type-specific params with examples, delivery constraints (verification, rate limits, webhook signing secret), and failure behavior (auto-disable). No gaps for agent to guess.

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% (3 params fully described in schema). Description adds significant value: explains type enum values with practical examples (e.g., 'items:["5.02"] = officer change'), details params objects for each type, and elaborates delivery options with verification requirements. Goes well 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 starts with a clear verb+resource: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This distinguishes it from siblings like list_subscriptions (listing) and unsubscribe (removal).

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 prerequisite: 'Requires a Pipeworx OAuth account'. Covers when to use each subscription type with concrete examples. Specifies default feed delivery and optional email/SMS with constraints (verification, cap). No ambiguity about context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds concrete behavioral details: returns category-bucketed questions each with exact tool+argument shape, and lists categories. No contradictions.

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

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

Description is relatively long but packs essential information. It front-loads the question phrase and lists categories efficiently. Some redundancy could be trimmed, but overall 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 fully explains the return format (category-bucketed example questions with tool+argument shapes). It is complete for an onboarding tool, covering purpose, usage, 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% but description adds value by explaining the topic parameter's possible values and behavior when omitted. It provides real-world usage context 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 returns category-bucketed example questions for Pipeworx, serving as an onboarding entry point. It lists specific categories and provides a clear verb ('returns') and resource ('example questions').

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call with or without the topic argument. Does not explicitly list when not to use, but context strongly implies it.

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

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

Discloses beyond annotations: row is deactivated not deleted, preserving historical events. Consistent with idempotentHint=true and destructiveHint=false.

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

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

Two sentences, no redundant content, front-loaded with purpose.

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

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

For a simple 1-param tool with no output schema, covers purpose, side effects, and constraints fully.

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

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

Schema coverage 100% with existing description. Description adds no extra meaning beyond 'by id'.

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 cancels a subscription by id, with specific verb 'cancel' and resource 'subscription'. Differentiates from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), guiding when to use. Lacks explicit when-not-to-use or alternatives, but constraint is clear.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial context beyond that: it enumerates all possible verdicts, explicitly warns that could_not_verify means the check did not happen and must not be treated as evidence, and distinguishes unsupported from could_not_verify. This is exactly the kind of behavioral depth an agent needs, and it doesn't contradict any annotation.

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 dense and front-loaded with trigger phrases and purpose, then systematically covers routing, outputs, and a critical caller warning. Every sentence adds distinct information, and the length is justified by the tool's complexity. However, it is quite long, and the final sentence about replacing 4–6 calls is persuasive rather than essential, so it doesn't reach a 5.

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 simple schema and lack of output schema, the description carries the full burden—and succeeds. It explains when to use, how routing works, what verdict values to expect, the exact meaning of could_not_verify and unsupported, and that responses include a citation. It also notes the limitation to public US companies for the financial path. The only tiny gap is not defining 'inconclusive', but that doesn't hinder an agent's basic 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?

The schema already covers both `claim` and `tolerance_pct` at 100% coverage, setting a baseline of 3. The description adds valuable semantics by giving concrete claim examples and explaining that tolerance_pct overrides the claim's implied tolerance, capping at 5 unless explicitly set. This extra operational guidance lifts it above the baseline.

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

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

The description opens with specific trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and states a clear verb+resource: natural-language claim verification against authoritative sources. It distinguishes itself from sibling tools by describing a verdict-producing pipeline and a structured SEC EDGAR path for financial claims, making it unambiguous when this tool is the right choice.

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?

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and further clarifies the automatic routing between SEC financial claims and grounded-pipeline claims. It also notes that it replaces 4–6 sequential calls. However, it doesn't formally name alternatives or exclusion scenarios, so it stops short of a 5.

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