Quickgo

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and no destructive behavior. The description adds meaningful context: default model behavior, BYO-key requirement for Anthropic with direct payment, and output structure (per-model details + combined view). This explains traits not captured by annotations.

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

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

The description is a single, well-structured paragraph of about 3 sentences. It leads with the core action, followed by details on defaults/options, and ends with use cases. Every sentence provides necessary information without redundancy.

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

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

Despite having no output schema, the description explicitly states the return format (per-model object with score, confidence, signals, raw_response, plus combined view). All four parameters are documented in the schema and described in the description. Annotations cover safety. 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%, so the baseline is 3. The description adds value by explaining the default model behavior for the models parameter, clarifying that _apiKey is passed through to Anthropic, and providing context about disambiguation for the context parameter. It also implies that omitting models uses only workers-ai.

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 a specific verb ('Probe') and resource ('LLMs for what they know... and score visibility'), clearly distinguishing the tool's purpose from sibling tools like ask_pipeworx, which are for direct queries. It also lists concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring).

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 usage context by listing three high-value use cases. However, it does not explicitly state when not to use this tool or name alternative tools (though sibling names provide implicit differentiation). The guidance is strong but stops short of explicit exclusion criteria.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds behavioral context: it routes to 5,529 tools, fills arguments, returns structured answers with stable citation URIs, and emphasizes it is the fast default entry point. It doesn't contradict annotations and adds value beyond the structured metadata.

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

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

The description is lengthy but each sentence adds actionable guidance: preference over web search, domain list, use cases, examples, and upgrade paths. It is front-loaded with the critical prioritization ('PREFER OVER WEB SEARCH'). While concise alternatives exist, the complexity of the tool justifies the detail; still, it could be trimmed slightly without losing 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?

Despite lacking an output schema, the description explicitly mentions the return format (structured answer with pipeworx:// citation URIs) and covers usage timing, source domains, and related tools. It addresses the tool's role as the default entry point and provides upgrade paths for edge cases. This makes the description complete for the tool's complexity.

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

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

The input schema covers 100% of parameters and describes the 'question' property with aliases, so the baseline is 3. The description adds examples of suitable queries (e.g., 'current US unemployment rate') but doesn't explain parameter syntax beyond what the schema provides. It does not compensate additionally for any schema gaps because there are none.

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 that the tool answers factual questions by routing them to appropriate tools and returning structured answers with citations. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives for specific use cases. The verb 'ask' and resource 'pipeworx' are contextualized with rich detail.

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: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions'. It also gives clear when-not-to-use instructions by directing users to ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions. Example queries help clarify intended usage scenarios.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses that the tool is currently identical to ask_pipeworx because no candidate is active (retired on 2026-07-26) and that live routing improvements may change behavior when a candidate is under test. This transparency about experimental status and the absence of a fallback role meaningfully complements the annotations.

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

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

The description is front-loaded with the tool's identity and purpose, and each of the four sentences contributes unique, non-redundant information: beta status, the identical-to-stable current state, usage instructions, and the non-fallback clarification. It is dense but well-organized, with no wasted words.

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

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

With no output schema, the description says only 'same response shape' without elaborating what that shape is, leaving a minor gap about return values. However, it explicitly ties the tool to ask_pipeworx (a sibling), making the behavior discoverable, and it thoroughly covers the experimental context, routing function, and current operational status. This is slightly incomplete but largely sufficient.

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

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

Schema coverage is 100%: all six parameters are documented as aliases for 'question,' and the schema itself fully explains the required parameter. The description adds no extra semantic value beyond noting 'same arguments' as ask_pipeworx, which is too generic to enhance parameter understanding. Per the baseline for high schema coverage, a score of 3 is appropriate.

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

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

The description immediately identifies the tool as a 'universal router' with the same 5,529 tools as ask_pipeworx, making its core purpose unmistakable. It also distinguishes this beta from the stable ask_pipeworx by noting 'candidate routing improvements' and calling itself the 'experimental edge,' differentiating it from the sibling stable router.

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

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

The description explicitly instructs: 'Use it exactly like ask_pipeworx when you want the newest routing' and clearly states that results are compared against the stable router to inform merge decisions. It also preempts misuse with 'Falls back to nothing — this IS a full working router,' clarifying when NOT to treat it as a fallback and implicitly directing users to ask_pipeworx for stable behavior.

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 well beyond the annotations, disclosing the exact return shape (success and refusal), refusal reasons, the extra LLM call cost, and the constraint to use only tool-result content. It aligns with readOnlyHint, idempotentHint, and destructiveHint without contradiction.

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

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

The description is dense but well-structured, front-loading the core value proposition. It covers purpose, behavior, return contract, and usage in three sentences, though the detailed return structures make it somewhat long.

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 fully explains success and refusal return values, the evidence/confidence fields, and the tradeoff vs. ask_pipeworx. It also provides domain examples (financial, legal, medical), making it complete for an agent to invoke correctly.

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

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

The schema has 100% coverage, describing the single 'question' parameter and its aliases. The description adds no additional parameter meaning beyond what the schema already provides, so the high-coverage 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 identifies the tool as a 'hallucination-resistant answer mode' that routes queries, fetches data, and extracts answers only from returned content. It distinguishes itself from the sibling ask_pipeworx by emphasizing grounding and evidence, making its unique purpose clear.

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

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

Explicit guidance is provided: use for high-stakes reads when answers will be quoted, cited, or acted on, and prefer ask_pipeworx for casual lookups due to the extra LLM call cost. This gives clear when-to-use and when-not-to-use instructions with an alternative.

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 is exceptionally transparent, detailing resolution confidence levels (high/medium/low/none), short-circuit behavior for low confidence and closed markets, spread handling with illiquidity warnings, cancellation rule parsing with specific examples and risk quantification, and news fallback fields. All of this adds value beyond the annotations (readOnlyHint, idempotentHint, etc.) and reveals no contradiction.

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

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

The description is comprehensive but verbose. Critical information is front-loaded, but the text then meanders through many detailed sections (e.g., resolver contract, parent event extractor, news fields, safety, resolution-rule risk). Some repetition exists (resolution details appear in multiple paragraphs). With better structuring (e.g., bullet points or clear sections), it could be more concise while retaining all 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?

The description provides exhaustive context about the tool's behavior, response structure, edge cases, and safety mechanisms. Despite lacking an output schema, it meticulously documents the return shape (result.market with specific fields like best_bid, model_probability; result.analysis conditions; result.evidence keyed by source; resolver contract details; parent event extractor; news fields with fallback info). This level of detail ensures an AI agent can correctly interpret and use the tool's 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% with clear parameter descriptions. The tool description does not add significant new meaning to the three parameters; it reiterates the input format for 'market' and mentions 'depth' implicitly, but provides no additional constraints or context. Baseline score 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 the tool's purpose: research a Polymarket bet by pulling relevant Pipeworx data in one call. It specifies the input formats (slug, URL, question text) and the high-level workflow (resolve, classify, fan out, return evidence packet plus comparison). This distinguishes it from sibling tools like polymarket_edges which focus on edge detection, making the purpose unambiguous.

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

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

The description explicitly provides usage examples: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It also gives extensive examples of classifiers and fan-out scenarios. However, it does not offer explicit guidance on when to avoid this tool or when to prefer alternatives like polymarket_edges or polymarket_arbitrage. The usage context is clear but lacks exclusionary 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?

Description adds significant context beyond annotations: reveals data sources (SEC EDGAR/XBRL, FAERS), explains handling of off-calendar fiscal years, and states sorting by primary metric. 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?

Informative and front-loaded with common query phrases. Slightly verbose but every sentence adds value; no wasted words.

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

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

Covers entity types, data sources, return format (paired data + citation URIs), and sorting. No output schema but description sufficiently explains output. Complete for an agent to use 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?

Enriches each parameter meaningfully: explains type enum values with specific data pulled, and values with examples and constraints. Schema coverage is 100%, but description adds substantial detail.

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 performs side-by-side comparison of 2-5 companies or drugs, pulling specific financial or adverse-event data. Distinguishes from sibling tools like entity_profile by emphasizing parallel lookups.

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

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

Explicitly advises to prefer over sequential lookups and lists natural language triggers. Does not provide when-not-to-use scenarios, but the guidance is strong and 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 substantial behavioral context beyond the annotations: account and paid-tier requirements, parallel tool routing, return packet structure (verbatim evidence, confidence, source, fetched_at, citation URIs), explicit gaps[] with no invention, contradictions[] for certain depths, semantic excerpting, and latency expectations. 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 but well-organized, front-loading the critical account requirement and alternative tool. Every sentence carries substantive information, though the length is considerable. A more paragraph-structured layout might improve scannability, but for a tool this complex, the detail is justified.

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 sufficiently explains the findings packet structure, gaps[], contradictions[], hop fields, and citation fetchability. It also covers prerequisites, timing, and limitations relative to news topics, making the description complete for an agent to decide when and how to invoke the 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 covers both parameters in detail (question natural language, depth with enum and behavior). The description reinforces this and adds practical context like 'broad/multi-part is fine' and how depth levels affect gap recovery and contradiction scanning. Some redundancy exists with the schema, but the extra guidance is helpful.

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

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

The description clearly states the tool performs grounded multi-source research across 1,455 structured data sources in one call, decomposing questions into facets and routing them to 5,529 tools in parallel. It explicitly distinguishes itself from open-web search and names the sibling ask_pipeworx as the alternative for single lookups, making the purpose and scope unambiguous.

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

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

The description provides explicit when-to-use guidance: best for broad/multi-part structured-data questions, use ask_pipeworx for single lookups, and prefer ask_pipeworx for breaking or colloquial current-news topics. It also notes account requirements and offers ask_pipeworx as fallback when not signed in, plus depth-level recommendations.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: returns top-N tools with full input schemas and curated examples, ready to call directly. No contradiction.

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

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

The description is somewhat lengthy but every sentence adds value. It is front-loaded with the core purpose and then provides context. Minor redundancy (e.g., listing many categories) 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 the tool's purpose (discovery) and complexity (6 params, no output schema), the description adequately covers what it returns (top-N tools with schemas) and when to use it. It lacks details on pagination but is sufficient for a discovery tool.

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

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

Schema coverage is 100% with all parameters described. The description adds meaning by mentioning aliases for 'query' (task, q, description, search) and providing examples. It also explains the output includes schemas and examples, adding value beyond the schema.

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

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

The description clearly states 'Find tools by describing the data or task' with a specific verb (find/discover) and resource (tools). It distinguishes from sibling tools like ai_visibility_check or ask_pipeworx by focusing on discovery rather than specific tasks.

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 'Call this FIRST when you have many tools available and want to see the option set.' Provides concrete examples of use cases (SEC filings, financials, etc.) and implies when not to use (when you need a single answer).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds important behavioral context: the patents source 'USPTO PatentsView API sunset May 2025 — soft-fails until reactivated', and the fallback chain 'GDELT→GNews'. No contradictions with annotations.

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

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

The description is information-dense but slightly long. It front-loads common query examples and then systematically lists outputs. Every sentence adds value, but some internal details (like the full list of outputs) could be more succinct. Still, it is well-organized and scannable.

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

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

No output schema exists, so the description must fully describe return values. It does so comprehensively: lists all fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and explains sources and fallbacks (patents sunset, GDELT→GNews). This is sufficient for an agent to understand what to expect.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds meaning beyond the schema: explains that 'value' can be a ticker or zero-padded CIK, explicitly warns that names are not supported, and clarifies that 'type' only supports 'company'. This added clarity justifies a 4.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company'. It specifies the verb ('profile'), resource ('US public company'), and scope ('cross-source'). It distinguishes from sibling tools like resolve_entity by explicitly mentioning 'names not supported — use resolve_entity first'.

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

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

Provides explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. Also clearly states when not to use: 'Names not supported — use resolve_entity first'. This gives clear context for tool selection.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds context about clearing sensitive data but does not elaborate on effects like irreversible deletion. No contradiction.

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

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

Two concise sentences that front-load the purpose and follow with usage guidelines. No wasted words.

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

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

For a simple 1-parameter tool with no output schema and clear annotations, the description covers purpose, usage, and parameter sufficiently.

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

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

Schema covers 100% of the single parameter with a clear description. The tool description mentions 'by key', which aligns but adds no extra 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 starts with a clear verb 'Delete' and specific resource 'previously stored memory by key'. It distinguishes itself from siblings by mentioning '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?

It explicitly states when to use: context stale, task done, clear sensitive data. It lacks a direct when-not-to-use statement but provides clear context.

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

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

The description adds value beyond the annotations by stating it is from QuickGO (EBI), is keyless, and lists the types of data returned (GO ids, names, aspect, evidence, taxon). Annotations already indicate safety, but the description adds specific behavioral context.

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

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

The description is a single, concise sentence that front-loads the core purpose, followed by a clarifying example. No extraneous information.

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

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

Given the tool has only 2 parameters, no output schema, and rich annotations, the description is sufficiently complete. It explains the source, required identifier, and what fields are returned, covering the essential needs for an agent to use the 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 description coverage is 100%, so the schema fully documents both parameters. The description adds context (e.g., 'identified by UniProt accession') but does not provide additional meaning beyond the schema, which justifies the baseline score of 3.

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

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

The description uses a specific verb ('list'), identifies the resource ('Gene Ontology annotations'), and specifies the key identifier ('UniProt accession'). It clearly distinguishes the tool's purpose from its siblings, which are mostly unrelated.

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

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

The description provides a clear usage context (need GO annotations for a UniProt ID) and includes an example, but it does not explicitly state when not to use this tool or mention alternatives among siblings.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds process details: fetches, extracts title/description/key links, emits standard format. No contradictions; it enriches the agent's understanding of 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?

Three sentences with front-loaded purpose and output format. No redundant phrases; every sentence adds value. Efficient and clear.

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 rich annotations and clear description of process and output, the description is mostly complete. However, it does not mention error handling (e.g., invalid URLs) or limitations, but given the tool's simplicity and annotation coverage, it is sufficient.

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

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

Schema coverage is 100%, with both parameters described. The description adds context about extraction and output format but doesn't provide additional parameter-specific semantics beyond what the schema already says. Baseline score of 3 is appropriate.

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

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

The description explicitly states the tool generates a production-ready llms.txt file for any URL, targeting AI crawlers. It specifies the action, resource, and purpose, and distinguishes itself from sibling tools by focusing on llms.txt generation, which is unique among the listed siblings.

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

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

The description provides clear use cases: getting a client's site indexed, drafting for own project, or auditing competitor's AI visibility. It lacks explicit when-not-to-use or alternatives, but the scenarios are well-defined and contextual.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds that it is keyless (no auth) and specifies the exact return fields, providing useful context beyond annotations.

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

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

Two concise sentences with no redundant information. Efficiently communicates source, action, return content, and access requirement (keyless).

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 lookup tool with one parameter and clear return fields listed, the description is complete. Annotations cover safety, and no output schema is needed given the description of return fields.

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

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

Schema coverage is 100% with a clear description for the only parameter 'id'. The description does not add additional meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states what the tool does: get a single GO term by ID, and lists the return fields. It distinguishes from siblings like search_terms by specifying single term lookup.

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

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

No explicit when-to-use or alternatives are given, but the purpose is obvious from the description and name. Implied usage for retrieving a specific GO term by ID.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, setting a baseline. The description adds value by listing the returned fields (id, type, params, created_at, etc.) and the purpose context, but does not introduce any new behavioral disclosure beyond what annotations cover.

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

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

The description is concise: two sentences, front-loaded with the primary action. Every sentence is informative without any fluff. Perfectly structured for an AI agent to quickly grasp the tool's 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 simplicity (one optional parameter, no output schema), the description provides complete context: what it does, what it returns, and when to use it. No gaps remain for an agent to correctly select and invoke it.

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

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

The single parameter 'include_inactive' is fully described in the input schema (100% coverage). The description does not add additional semantic meaning beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' – a specific verb and resource. It distinguishes from sibling tools like subscribe and unsubscribe by mentioning the purpose of reviewing before adding or canceling.

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 when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear guidance on appropriate use cases, distinguishing it from subscription management actions.

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 are all false (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), providing no behavioral insight. The description fills this gap by disclosing the claim_token mechanism for anonymous filing and later retrieval, rate limits (5 per identifier per day), quota exemption, and the team's daily digest review. Description fully contradicts no 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?

Although longer than average, every sentence serves a distinct purpose: purpose, when to use, exclusion, parameter guidance, token behavior, roadmap impact, rate limits, and cost. Content is front-loaded with the primary purpose, and there is no filler or redundancy.

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

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

This is a complete description for a feedback tool of moderate complexity. It covers target audience, specific use cases, exclusions, token-based follow-up, rate limits, cost, and even the team's response cadence. No output schema exists, but the description fully compensates by clarifying the claim_token return flow.

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 extra value by explaining the claim_token usage with an example ('pipeworx_feedback({claim_token:"pwfb_…"})') and clarifying message best practices ('Don't paste the end-user's prompt'). It doesn't add much beyond the schema for type/context, but the claim_token semantics push it to a 4.

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

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

The description immediately states a clear verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It lists specific feedback types (bug, feature, data_gap, praise) and clearly differentiates from sibling tools like ask_pipeworx or discover_tools by focusing on reporting issues to the Pipeworx team.

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-to-use scenarios ('Use when a tool returns wrong/stale data...', 'when a tool you wish existed isn't in the catalog...', 'when something worked surprisingly well') and a clear exclusion: 'ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead.' It even offers a fallback if unsure.

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 non-destructive. The description adds valuable context: data source (CF analytics-engine), privacy (no PII), caching behavior (5min-1h), and aggregation details. No contradiction with annotations.

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

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

Description is well-structured: hook sentence, explicit output, use-case list, then data source and caching. Every sentence adds value without redundancy. 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?

Given the tool's simplicity (one optional parameter, no output schema), the description covers purpose, output components, data source, privacy, and caching. It is fully informative for an agent to decide when 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?

Only one parameter (window) with enum values. The description explains how window choice affects results ('shorter windows surface what's hot right now; longer windows show steady-state demand'), adding meaningful context beyond the schema's basic enumeration.

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 specific verb+resource: 'Returns the top tools, top packs, and total call volume over a recent window'. It distinguishes itself from siblings by focus on trending signals, and the title reinforces this.

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

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

Three explicit use cases are provided (discovering hot data, confirming canonical tools, seeing alignment). However, it does not explicitly contrast with similar sibling tools like 'discover_tools' or mention when not to use 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 internal logic: monotonicity violations, partition-sum checks, Jaccard similarity filter, placeholder rejection, and fill check distinguishing theoretical vs realizable edge. This goes well beyond the readOnlyHint 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?

Well-structured with front-loaded summary, clear mode breakdowns, and detailed sections. Slightly verbose but each sentence adds value given complexity.

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?

Complete for complex tool: covers all modes, parameters, internal checks, response structure (opportunities[], partition_check fields, fill check details), and links to related tool. No output schema but description compensates adequately.

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?

Adds significant meaning beyond the schema: explains event slug format with examples, describes topic behavior as cross-event search, and covers no-args case. Schema coverage is 100% but description enriches understanding.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection with specific methods.

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 each mode: no args for trending scan, event for specific market, topic for cross-event scan. Also directs to polymarket_fill_risk for custom sizing, providing clear alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds extensive behavioral context: caching at KV level, response structure with segments and diagnostics, edge calculation details, and 24h-move warnings. 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 overly verbose with multiple paragraphs and highly detailed algorithm specifications. Important information is not front-loaded; the core purpose and usage could be summarized in 2-3 sentences. The length hinders quick comprehension.

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 comprehensively details the response structure (by_segment, diagnostics, fed_candidates), model families, edge calculation, caching policy, and filter knobs. All 9 parameters are contextualized. Extremely complete for a complex tool.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds context like 'Tradeable-edge knobs' and elaborates on defaults and behavior (e.g., slippage considerations). However, the additional value beyond the schema is modest, 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 tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It distinguishes from sibling tools like polymarket_arbitrage by its specific focus on Pipeworx disagreement, and from polymarket_edge_tracker by being a comprehensive scan.

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 is built for 'what should I bet on today' and notes agents discover opportunities without paging hundreds of markets. It implies usage for finding Pipeworx-disagreed bets but does not explicitly exclude alternatives or state when not to use.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds critical behavioral details: data source (daily snapshots), response structure (tracked, expired, snapshot_dates), limits (60-day TTL, not intraday), and edge_pp_net sign meaning. 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 dense and front-loaded with the core question. It could be slightly more concise but every sentence provides unique value. 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?

Despite lacking an output schema, the description fully explains the response structure (tracked[], expired[], snapshot_dates[]), edge_pp_net sign, and limits. Covers all necessary context for correct use.

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

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

Schema coverage is 100% for both parameters. The description adds context: default values (14 days, '1wk'), clamp for days, and explanation of window family. Only minor additions beyond schema.

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

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

The description clearly states the tool provides edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?'. It distinguishes from sibling tools like polymarket_edges by focusing on temporal analysis.

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 explains when to use the tool (to differentiate fresh vs. old edges) and provides context for interpreting results. It does not name alternative tools but the purpose is clear enough to infer.

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 include readOnlyHint, idempotentHint, and non-destructive. The description adds rich behavioral details: walks the ladder, returns specific fields like slippage and fill quality, and emphasizes risk of thin books and partial basket fills converting arb to directional position.

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

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

Well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) and front-loaded purpose. However, it is somewhat verbose and could be trimmed without losing essential information.

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

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

Despite no output schema, the description exhaustively lists return fields for both single-market (top_of_book, vwap_fill_price, slippage_pp, etc.) and basket (theoretical_sum, capture_ratio, thin_legs, etc.), providing complete contextual understanding.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description further elaborates: explains side defaults for single-market vs basket, market vs event distinction, and size_usd interpretation (spend vs target proceeds vs settlement notional). Adds significant meaning beyond schema.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishing between single-market and basket modes. It is specific and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly advises 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', providing clear context when to use and rationale for avoiding partial fills.

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?

Extensive behavioral disclosure beyond annotations: safety fields (compatibility_warning, temporal_alignment, skipped counters) and their interpretations. No contradictions.

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

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

Well-structured but verbose (10+ sentences). Some redundancy in mentions of pre-mapped shortcuts.

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

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

Describes response structure and safety fields despite no output schema. Covers scenarios with temporal alignment and compatibility warnings.

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 description adds examples and explains how explicit overrides topic mapping. Enhances parameter understanding.

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

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

The description clearly states it calculates cross-venue spread between Kalshi and Polymarket for same outcome. Differentiates from siblings by focusing on cross-venue arbitrage.

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

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

Explains two modes (topic shortcuts and explicit tickers) and warns about compatibility warnings. Provides context on when spreads are meaningful, but doesn't explicitly mention when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating safe, idempotent reads. The description adds behavioral context: the tool is scoped to an identifier (anonymous IP, BYO key hash, or account ID), which is not covered by annotations. No contradictions.

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

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

The description is three sentences, each earning its place: first sentence defines primary action, second explains use cases and scope, third mentions related tools. No redundant information.

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

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

Given the tool's simplicity (1 parameter, no output schema, clear annotations), the description is complete. It covers usage, scoping, pairing with siblings, and the two invocation modes.

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

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

Schema coverage is 100% with one optional 'key' parameter. The description adds value by explaining the two modes: retrieve a specific key or omit to list all keys. This goes beyond the schema's basic type definition.

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

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

The description clearly states the tool retrieves a previously saved value via 'remember' or lists all keys when no key is provided. It uses specific verbs and resources (retrieve, list keys) and distinguishes from sibling tools like 'remember' and 'forget'.

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

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

The description explains when to use the tool (look up context stored earlier) and explicitly mentions pairing with 'remember' to save and 'forget' to delete. It does not explicitly state when not to use it, but the usage 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, idempotentHint=true, etc. The description adds useful behavioral details: it returns the most recent alerts, explains the mark_read parameter's effect, and notes the return 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?

The description is a single paragraph with clear front-loading of purpose. Every sentence contributes: main action, return fields, filters, mark_read behavior, and note about polling. No wasted words.

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

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

While the description covers key aspects, it omits explanation of the 'unread_only' parameter, which is present in the schema. Since there is no output schema, the description should fully explain parameters. The schema covers it, but the description misses it slightly.

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 context for 'type', 'since', and especially 'mark_read' (explains its side effect). It does not mention 'limit' or 'unread_only' but those are clear from schema. The added value justifies one point above baseline.

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

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

The description starts with a clear verb+resource: 'Pull fired events from your subscription feed.' It specifies what is returned (source, citation_uri, payload) and how to filter (type, since). No sibling tool has similar purpose, so differentiation is not needed.

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 states that polling works fine and suggests an alternative REST endpoint for scripts/dashboards. It implies the tool is for programmatic use. However, it does not explicitly clarify when not to use the tool or contrast with 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 declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds behavioral details: fans out to three sources, fallback mechanism, soft-fail for USPTO, accepted date formats. No contradictions; all behaviors are consistent 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 but well-structured with front-loaded query examples. It covers all necessary aspects, though slightly verbose in detailing fallback logic. Every sentence serves a purpose, but some could be combined for brevity.

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

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

Given the tool's complexity (multi-source, fallback, date formats, return structure), the description is complete. It explains return structure (changes[] grouped by source, total_changes, citation URIs) despite no output schema. No gaps identified.

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

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

Schema coverage is 100% with descriptions for all three parameters. The tool description adds value by giving examples of relative shorthand ('7d', '30d', '3m', '1y') and recommending '30d' or '1m' for typical monitoring, providing 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 explicitly states the tool provides a change feed for a company from multiple sources (SEC EDGAR, GDELT/GNews, USPTO) within a time window. It distinguishes from sibling tool 'entity_profile' by specifying when to use each. The verb 'change feed' and resource 'company' are specific and clear.

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

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

The description provides explicit query patterns (e.g., 'what's new with X', 'latest on Y') and recommends using 'entity_profile' for static profile instead. It also explains fallback behavior (GDELT→GNews) and date format options, offering clear when-to-use and when-not-to-use guidance.

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

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

Annotations indicate idempotent and non-destructive. Description adds key-value scoping by identifier, persistent memory for authenticated users, 24-hour retention for anonymous. No contradictions.

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

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

Front-loaded with primary purpose, then usage guidance, then storage details and links to siblings. Every sentence adds value, 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?

Covers storage, scope, retention, and pairing with recall/forget. No output schema but return value is not critical for simple storage. Minor gap: no mention of update behavior (idempotent implies overwrite), but that's covered by annotation.

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. Description adds usage examples but not essential parameter details beyond schema. 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?

Clearly states the tool saves data for reuse across sessions, gives concrete examples (resolved ticker, target address, user preference), and distinguishes itself from siblings recall and forget.

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

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

Explicitly says 'Use when you discover something worth carrying forward... so you don't have to look it up again', mentions pairing with recall/forget, and describes authentication scoping with retention periods for authenticated vs anonymous users.

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

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

Annotations already indicate read-only, idempotent, and non-destructive, and the description adds rich behavioral detail: internal multi-endpoint cascading, graceful degradation if external sources fail, and explicit statement of unresolved identifiers. This goes well beyond the annotations and provides meaningful operational expectations.

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-organized with examples, supported types, and degradation notes. Every sentence adds value, and the structure makes it easy to scan despite its length. A slight reduction would be possible, but the complexity of the tool justifies the detail.

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 two-parameter schema and no output schema, the description is exceptionally complete. It covers input formats, output behavior, source attribution, unresolved identifiers, and failure-mode degradation. No critical gaps remain for effective tool selection and invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances parameter meaning by explaining input variants (ticker/CIK/name for company, brand/generic for drug) and tieing them to specific outputs (CIK/ticker/LEI/FIGI, RxCUI). It adds nuance like '10-digit CIK' and 'when a ticker is implied' that the schema doesn't capture.

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

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

The description states the tool resolves user-spoken names to canonical identifiers, with concrete examples (ticker, CIK, LEI, RxCUI) and explicit supported types. It distinguishes from sibling tools by positioning itself as the first stop for name-to-ID conversion.

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

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

Clearly says 'Use FIRST whenever you have a name but need an ID,' which is explicit when-to-use guidance. It does not name specific alternative tools or when-not-to-use scenarios, but the context and comprehensiveness of the description make the usage context unambiguous.

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 cover safety. The description adds value by revealing it internally calls ai_visibility_check and returns a ranked list with specific metrics. No contradictions.

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

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

The description is concise (4 sentences) and front-loaded with the main action. Every sentence adds value without redundancy.

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

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

Given four parameters and no output schema, the description covers purpose, internal mechanism, parameter roles, and output structure (ranked list with score, confidence, signal density). It is fairly complete but could mention entity count constraint (2-8) which is in schema.

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

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

Schema coverage is 100% and the description enriches parameter understanding: it explains the first entity is the subject, models can be omitted for default, API key purpose, and context use. This goes 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 compares AI visibility across multiple entities side-by-side, using ai_visibility_check internally. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison) by focusing on AI visibility ranking.

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 it is useful for competitive AI-marketing audits and implies multiple entities. It could be improved by explicitly stating when not to use (e.g., single entity) and naming alternatives, but the context is clear enough.

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 (readOnly, idempotent), description adds that bundlephobia first measurement can take 5-30s, partial failures degrade gracefully, and sources_failed list timeouts. 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 thorough but slightly verbose. However, it is front-loaded with purpose and organized into use cases and ecosystem notes. No wasted sentences.

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

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

Despite no output schema, description details return values: summary block, advisories, links, recent versions. Also covers ecosystem limitations and graceful degradation.

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?

Adds meaning beyond schema: version defaults to latest, scoped packages accepted. Schema coverage is 100%, but description provides valuable context.

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

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

The description clearly states it's a composite check for 'should I add this npm package' covering license, advisories, version history, and bundle size. It uses a specific verb-resource pair and distinguishes from siblings by focusing on npm packages.

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

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

Explicitly states when to use: when agent asks about safety, popularity, size, or cost of adding a package. Also specifies NPM-only in v1 and directs other ecosystems to alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds the 'Keyless' detail (no API key needed) and specifies the return format (id + name) and source (QuickGO EBI). This provides useful behavioral context beyond annotations, though rate limits or pagination are not mentioned.

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

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

The description is two sentences with no wasted words. It front-loads the main action and adds key details 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 search tool with two parameters, full schema coverage, and rich annotations, the description covers the purpose, return format, source, and authentication requirement. It is nearly complete for the complexity level, though it could mention the maximum limit (already in schema) or potential empty results.

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

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

Schema coverage is 100%, but the description adds value by characterizing 'query' as a free-text keyword search with an example ('apoptosis') and noting the return format. This helps the agent understand parameter semantics beyond the schema's description.

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

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

The description clearly states the tool searches Gene Ontology terms by keyword and returns matching terms (id + name). It uses a specific verb and resource. However, it does not explicitly differentiate from sibling tools like 'get_term' or 'search_within', missing the chance to help an agent choose between 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?

The description provides no guidance on when to use this tool versus alternatives. It mentions 'Keyless' (indicating no authentication), but does not specify prerequisites, exclusions, or contexts where other tools (e.g., 'get_term') would be more appropriate.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds rich behavioral context: truncation at 200K chars, embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, and that longer inputs are flagged. No contradiction with annotations.

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

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

Single paragraph of ~120 words, well-structured: purpose, usage, pairing, technical details. Every sentence adds value; 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?

No output schema, but description explains return values (top-N passages with character offsets and similarity scores). Mentions grounding and pairwise with ask_pipeworx_grounded. Lacks details on similarity score range or pagination, but sufficiently complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions. Description adds context: 'max ~200K chars' for text, natural-language query with examples for query, and default/max values for limit. This goes beyond schema, so baseline 3 becomes 4.

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

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

The description clearly states it performs semantic search inside a fetched record, with specific examples (SEC 10-K, article, tool result) and return values (passages with offsets and similarity scores). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and contrasting with fetching via the gateway.

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 when the record is too big to cram into the prompt' and mentions saving context. It does not explicitly state when not to use, but the condition is clear. Also suggests pairing with 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?

The description adds rich behavioral context beyond annotations: requires OAuth account, returns new subscription id, lists supported types with examples, and details delivery channels including SMS caps and webhook auto-disable. 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 well-structured with clear sections but is relatively long. Every sentence adds value, though some minor tightening could improve conciseness.

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

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

Despite no output schema, the description explains the return value (subscription id) and covers all aspects: input parameters, requirements, use cases, delivery details, and limitations. It is fully complete for a creation tool with 3 parameters.

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 significant value: explains type enum use cases (e.g., sec_8k items for officer changes), provides expanded params examples, and details delivery constraints (verification, caps, webhook signing). It meaningfully supplements 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 creates a proactive monitoring subscription to a live-data event stream, with specific verb and resource. It distinguishes from sibling tools like unsubscribe 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?

The description specifies when to use (creating subscriptions), required account type (Pipeworx OAuth), and provides examples for each subscription type. It does not explicitly state when not to use or name alternatives, but the context is clear.

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

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

The description goes beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by explaining that the tool returns category-bucketed example questions with exact tool and argument shapes, drawn from a live catalog of thousands of tools. This adds significant behavioral context without contradicting 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 well-structured, starting with example queries and the tool's purpose, then detailing the output and usage instructions. It is efficient but could be slightly more concise without losing clarity. Still, each sentence adds value.

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

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

Given the tool is a discovery tool with no output schema and a single optional parameter, the description thoroughly explains what the tool returns (example questions with tool shapes), how it works (live catalog), and when to use it. It addresses all necessary contextual information 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?

With 100% schema coverage and a single optional parameter, the description adds value by explaining that omitting the topic gives a cross-category spread, and lists the possible topic values. It clarifies the effect of the parameter beyond the schema's brief description.

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

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

The description clearly states the tool's purpose as an onboarding entry point for a new agent, returning category-bucketed example questions. It explicitly mentions typical user queries like 'what can you do?' and 'getting started', and distinguishes it as the first tool to use when unfamiliar with Pipeworx's capabilities.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools', providing clear guidance on when to use. It also explains how to call with no arguments for full spread or with a topic to focus. However, it does not explicitly mention when not to use this tool or provide exclusion criteria.

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

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

Annotations provide idempotentHint=true and destructiveHint=false. Description adds that the row is deactivated (not deleted) and historical events remain available, giving behavioral context 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?

Two short sentences, front-loaded with action, no redundant information. Every sentence adds value.

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

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

No output schema present; description explains effect (deactivation) and ownership constraint. Could mention error handling for invalid id, but overall adequate for a simple mutation tool compared to siblings.

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 describes id parameter as 'Subscription id (uuid) returned by subscribe.' Description does not add new meaning; it only restates 'by id'. With 100% schema coverage, baseline 3 is appropriate.

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

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

Description states 'Cancel a subscription by id' with specific verb-resource. Distinguishes from sibling tools like subscribe and list_subscriptions by focusing on cancellation and ownership enforcement.

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 ownership enforcement ('only cancel your own subscriptions'), giving clear context for when to use. Does not explicitly mention when not to use or alternatives, but the condition 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 goes well beyond the annotations (readOnly, openWorld, idempotent). It discloses the two verification routes, the specific verdict types returned, the meaning of 'could_not_verify' (verification_error, not evidence) and 'unsupported' (no source found), and even warns callers not to display could_not_verify as evidence. It also explains the default and override behavior of tolerance_pct. This is rich, non-obvious 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?

While the description is detailed, every sentence delivers essential information. It opens with recognizable query patterns, explains the tool's scope, breaks down two code paths, describes return values and edge cases, and ends with a clear 'Replaces 4–6 sequential calls' statement. The structure is logical and efficient with 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?

The description is complete for a tool with no output schema. It explains the return format (verdict, actual value with citation, reasoning) and explicitly defines the two failure verdicts ('could_not_verify' and 'unsupported'), including how to treat them. With annotations already covering safety and idempotency, and parameters fully documented in schema, the description fills all 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%, so baseline is 3. The description adds meaningful context beyond the schema: it gives natural-language examples for the claim parameter and explains how tolerance_pct overrides the implied tolerance (e.g., set 1–2 for hallucination detection) and that the default is capped at 5. This helps callers know how to set the parameter in different scenarios.

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: natural-language claim verification against authoritative sources, with explicit query examples ('Is it true that…', 'fact check' etc.). It specifies the resource (claims) and the verb (validate/verify), and it stands apart from siblings by emphasizing its end-to-end claim-checking capability that replaces multiple sequential calls.

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

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

The description says 'Use whenever the agent needs to check whether something a user said is factually correct,' which is a clear use case. It also explains the two distinct paths (company financial claims via SEC EDGAR vs. other claims via grounded pipeline), but it does not explicitly name alternative tools to use instead or provide exclusion criteria. This is clear context without explicit alternatives.

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