Sgd

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds behavioral context: default model (free), costing model for Anthropic (users pay directly), and the return format. This complements the annotations well.

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

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

The description is a highly efficient 4-sentence paragraph. It is front-loaded with the core action, then progressively adds key details (default model, API key use, return format, use cases). No superfluous text.

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

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

Despite no output schema, the description adequately describes the return format (per-model {score, confidence, signals, raw_response} + combined view). It covers the tool's purpose, parameters, and use cases, making it complete for an agent to decide when and how to 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?

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining the supported models for the 'models' parameter ('workers-ai', 'anthropic') and clarifying that _apiKey is passed through to api.anthropic.com, with cost implications.

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 precise verbs ('Probe', 'score visibility') and specifies the resource ('one or more LLMs'). It clearly distinguishes the tool from siblings by focusing on cross-model visibility scoring, with specific use cases like AI-marketing audits.

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

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

The description provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use the _apiKey parameter (only for Anthropic). However, it doesn't mention when NOT to use this tool or suggest alternative tools, which would have earned a 5.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds that it routes and fills arguments, returns stable citation URIs, and works on every tier with one fast call. This provides useful 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 longer than typical but well structured with a clear 'PREFER OVER WEB SEARCH' hook, category list, examples, and alternative guidance. Every section serves a purpose given the tool's broad scope, though some redundancy exists between the opening and the 'Use whenever' phrasing.

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 router tool with no output schema, the description covers purpose, usage signals, alternatives, and return format (structured with citations). It also notes it works on every tier and is the default entry point, providing sufficient context for an agent to decide when to 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?

Schema coverage is 100% for the single semantic parameter 'question' plus aliases. The description enriches this by giving numerous example queries and explaining natural-language use cases, which goes beyond the bare schema. It helps the agent understand what constitutes a valid question.

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

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

The description clearly states the tool routes questions to 5,529 tools across 1,455 sources and returns structured answers with citation URIs. It distinguishes itself from siblings by positioning as the default entry point and naming alternatives like ask_pipeworx_grounded and deep_research. The verb 'routes' plus resource scope makes the purpose specific and unambiguous.

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

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

The description explicitly says to prefer this over web search for specific data categories, lists trigger phrases like 'what is' and 'look up', and provides when-to-step-up guidance for grounded answers and deep research. It clearly distinguishes when to use this tool versus alternatives, making it an excellent usage guide.

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

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

The description adds significant behavioral context beyond the annotations: it discloses the experimental nature ('experimental edge'), live candidate routing under test, current equivalence to ask_pipeworx, and the no-fallback guarantee. These are meaningful traits not captured by readOnly/openWorld/idempotent hints. 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?

Four sentences front-load the core purpose, then efficiently cover candidate status, usage, and non-fallback behavior. Every sentence adds essential, non-redundant information; the text is dense but not bloated.

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

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

For a complex 5,529-tool router with no output schema, the description covers the essential context: identical to ask_pipeworx, candidate improvements, current exact match, and the comparison workflow. This is sufficient for an agent to invoke the tool 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 input schema already provides 100% coverage for all parameters, including the required 'question' and its aliases. The description only references 'same arguments' without adding new parameter-level detail, so the schema carries the burden.

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 beta version of ask_pipeworx, stating it is an identical universal router with 5,529 tools. It distinguishes itself from the sibling ask_pipeworx by emphasizing the experimental/candidate routing improvements and explicitly says to use it 'exactly like ask_pipeworx.'

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

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

Provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It also clarifies when no candidate is active, making the selection criteria 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds rich behavior: it uses only the tool result, returns a structured response with evidence and confidence, includes explicit refusal reasons, and mentions the extra LLM call cost. 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 dense but well-structured: it opens with the core promise, then details routing, extraction, return format, refusal format, use cases, and cost tradeoff. Each sentence earns its place, making it appropriately sized for the tool's 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?

The tool is complex, but the description covers all essential context: return shape, refusal reasons, extra cost, and comparison with ask_pipeworx. Although no output schema is present, the description details the return object and refusal cases, making it complete for invocation.

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

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

Schema description coverage is 100%, with each parameter alias already documented as 'Alias for question.' The description adds no new parameter meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states a specific mode: 'Hallucination-resistant answer mode' with a clear verb 'EXTRACTS the answer using ONLY what the tool result contains.' It distinguishes from siblings by emphasizing grounded extraction and refusal behavior, while noting 'Same routing as ask_pipeworx.' This is a specific verb+resource with clear differentiation.

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: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' This names the alternative and states when not to use the tool, offering clear context and exclusions.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds extensive behavioral details: fan-out logic, response shapes, edge cases (low confidence, closed markets, wide spreads), resolution-rule risk, and safety short-circuiting. 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 very long (multiple paragraphs) with exhaustive detail. While front-loaded with purpose, subsequent sections could be more structured (e.g., bullet points). Every sentence adds value, but overall verbosity reduces 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?

No output schema exists, so description must compensate fully. It does: explains response shapes (market, analysis, evidence), resolver contract, parent event extractor, news fields with fallback logic, and safety checks. Covers all relevant behavioral aspects and edge cases.

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

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

Input schema has 100% coverage with descriptions for each parameter. The description adds meaningful context: explains what `market` accepts (slug, URL, question text), `depth` enum options with defaults, and `include_raw` purpose and size implications. Schema does the heavy lifting, 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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It lists inputs, steps, and outputs, and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on a specific bet research use case.

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: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Provides usage examples. Lacks explicit when-not-to-use or alternative tool suggestions, which would push it to 5.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive nature. Description adds valuable behavioral context: parallel execution, handling of off-calendar fiscal years, sorting by primary metric, and provision of citation URIs. 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 front-loaded with natural language triggers, then explains behavior, entity-specific outputs, and performance benefits. 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 the tool's complexity (parallel lookup, multiple data sources, dynamic sorting), the description covers all essential aspects. It mentions output format (paired data + URIs) despite no output schema.

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

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

Schema has 100% coverage with descriptions. Description adds further meaning by detailing what data is pulled for each type (company: revenue, net income, cash, debt; drug: FAERS counts, FDA approvals, trials) and constraints like maxItems 5.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It provides example natural language triggers and explicitly distinguishes itself from siblings by replacing sequential single-pack 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 instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also clarifies when to use based on entity type and provides specific data sources for each.

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 annotations (readOnly, idempotent, non-destructive), the description discloses critical behaviors: account requirements, paid plan for thorough depth, the tool is NOT open-web search, returns gaps[] never invented, performs second-hop iteration, includes contradictions[], and provides time expectations. It adds substantial context without contradicting annotations.

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

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

The description is comprehensive but presented as a single dense paragraph, which hurts scannability. It covers many important details, each earning its place, but the lack of structure (headings, bullets) and length make it feel verbose. It is not concise, though not wasteful either.

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 and absence of an output schema, the description is remarkably complete: it explains the findings packet, gaps[], contradictions[], citation fetchability, semantic excerpting, and time expectations. It also handles account prerequisites and alternatives, leaving no major contextual void.

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?

Even though the input schema already describes both parameters, the description enriches the depth semantics (quick=3, standard=5 with gap recovery, thorough=8 paid with iterative hopping) and clarifies that question can be broad/multi-part. It also explains the meaning of hop fields and citation_uri, going far 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 performs grounded multi-source research across Pipeworx's structured data sources in one call, decomposing questions and routing to specialized tools. It explicitly distinguishes itself from open-web search and from ask_pipeworx, making its purpose unmistakable.

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

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

The description gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, with a single lookup pointing to ask_pipeworx, and breaking/current-news topics also pointing to ask_pipeworx. It also provides a conditional fallback (use ask_pipeworx if not signed in).

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, idempotent, non-destructive. Description adds context that results are 'ready to call directly, no second schema lookup needed,' providing extra behavioral info beyond annotations. No contradictions.

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

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

Description is front-loaded with the main purpose, uses bullet-like listing for domains, and 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?

For a discovery tool with high-quality annotations and schema, the description covers purpose, return value, and usage context completely. No output schema needed as return is described 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?

Schema coverage is 100%, so baseline is 3. Description gives example queries but does not significantly add meaning beyond the schema's aliases and descriptions.

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

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

The description clearly states the tool finds tools by describing data or task, lists specific domains, and explains what it returns (top-N tools with names, descriptions, schemas). It distinguishes from siblings by advising to call this first for browsing.

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

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

Explicitly states use case: 'Use when you need to browse, search, look up, or discover what tools exist' and advises 'Call this FIRST when you have many tools available.' Could be improved by stating 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Description goes beyond by detailing internal fan-out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), specific return fields (cik, filings, fundamentals, patents, news, LEI), and known limitations (USPTO PatentsView API sunset May 2025 with soft-fall behavior). No contradiction with annotations.

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

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

Description is front-loaded with example queries and key instruction ('ALWAYS PREFER...'). It is detailed but each sentence provides essential information. Minor wordiness can be excused given the complexity of the tool; still very effective and well-structured.

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

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

No output schema exists, so description fully compensates by enumerating return components (cik, company_name, recent_filings with URIs, fundamentals with specific fields and sorting, patents, news, LEI). It also covers edge cases (patents sunset, soft-fall, name not supported). The description leaves no ambiguity about what the tool returns and its limitations.

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 significant meaning beyond schema: explains 'type' is limited to 'company' for now, and 'value' accepts ticker or zero-padded CIK, not names, with explicit example ('AAPL' or '0000320193'). It also cross-references resolve_entity for name lookup, which aids correct parameter selection.

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

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

Description starts with concrete example queries and clearly states 'full cross-source profile of a US public company in ONE parallel call'. It distinguishes from sibling tool 'resolve_entity' by noting that names must be resolved first. It also explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups', providing clear purpose and differentiation.

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

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

Description provides explicit when-to-use guidance: 'when the user asks for a holistic view'. It also gives when-not-to-use: 'names not supported (use resolve_entity first if you only have a name)'. Additionally, it warns about patents sunset and soft-fall behavior, and specifies the need for ticker or CIK input.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, covering safety and idempotency. The description adds 'clear sensitive data' as motivation but doesn't disclose additional behavioral traits beyond annotations.

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

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

Two sentences, front-loaded with the action. No wasted words; every sentence serves a purpose.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage context, and relationships. No gaps.

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

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

With 100% schema description coverage, the schema already documents the 'key' parameter as 'Memory key to delete'. The description does not add meaning beyond that, 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 'Delete a previously stored memory by key', using a specific verb and resource. It distinguishes itself from sibling tools like 'remember' and 'recall' by focusing on deletion.

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: 'when context is stale, the task is done, or you want to clear sensitive data'. Also advises pairing with siblings 'remember and recall', giving clear context and alternatives.

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

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

Discloses the process: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown format. Aligns with annotations (readOnlyHint, idempotentHint) and adds details beyond them, such as the output being a single text blob ready to deploy.

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?

Efficiently structured in three sentences: purpose and format, process, use cases. No unnecessary words, and critical information is front-loaded.

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

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

Given two parameters with full schema and no output schema, the description adequately covers the output format ('single text blob ready to drop at site-root/llms.txt'), the process, and usage context. No gaps for a tool of this 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%, so baseline is 3. The description repeats the schema descriptions for 'url' and 'max_links' (including default and max values) but does not add new semantic information beyond what the schema already provides.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifies the verb 'generate' and the resource 'llms.txt file', and distinguishes from siblings by listing specific use cases such as indexing, drafting, and auditing.

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

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

Explicitly lists three distinct use cases: getting a client's site indexed, drafting for own project, and auditing competitor sites. This provides clear context on when to use this tool and implicitly guides away from using it for unrelated tasks handled by siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds valuable context: it lists the returned fields (standard name, systematic name, SGDID, description, locus type, aliases), and states 'Keyless' indicating no authentication required. 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: two sentences that front-load the purpose and then provide essential details (acceptable identifiers, returned fields, keyless). No wasted words.

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

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

Given no output schema, the description fully explains the return values. It also covers input variants and keyless access. For a simple lookup tool, the description is complete and leaves no major gaps.

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

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

Schema description coverage is 100%, with the schema already listing acceptable identifier types. The description reiterates this but adds the context that it is for yeast genes. This adds minimal new semantic 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 it looks up a single yeast gene/locus, specifying the organism (S. cerevisiae) and the source (SGD). It distinguishes itself from sibling tools like search_genes (for multiple genes) and get_gene_go (for GO annotations) by being a single-gene lookup.

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

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

The description implicitly indicates usage for single gene lookups vs search_genes for multiple. The note 'Keyless' informs that no API key is needed. However, it lacks explicit when-not-to-use instructions or direct sibling comparisons.

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

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

Annotations already cover read-only, open-world, idempotent, non-destructive behavior. The description adds that it returns GO terms with aspect and evidence, which is useful context beyond annotations.

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

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

The description is two sentences covering purpose, input, and output without unnecessary words. Every sentence adds value.

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

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

Given no output schema, the description explains the return format (GO id, aspect, evidence). The parameter is well-documented. Adequate for a straightforward retrieval tool.

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

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

Schema coverage is 100%, and the description adds examples of acceptable ID formats (systematic name, gene name, SGDID), enhancing the schema description which already lists them.

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 retrieves Gene Ontology annotations for yeast genes from SGD, specifying the species, database, and return type. This distinguishes it from siblings like 'get_gene' (general info) and 'search_genes'.

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

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

The description mentions 'Keyless' and accepts multiple ID formats, providing clear input guidelines. It does not explicitly contrast with alternatives but implies usage for GO annotations specifically.

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

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

Annotations already provide readOnlyHint, destructiveHint, idempotentHint, openWorldHint. Description adds that it lists active subscriptions by default and returned fields, but doesn't add significant behavioral context beyond annotations.

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

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

Two sentences, front-loaded with action and output, 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?

No output schema, but description explains return fields. Usage context provided. Simple tool, fully covered.

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

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

Schema covers 100% of the single parameter (include_inactive) with a clear description. Description does not add extra meaning beyond listing it.

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

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

Description clearly states 'List the caller's active subscriptions' and lists returned fields (id, type, params, etc.). Distinguishes from siblings like subscribe and unsubscribe.

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

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

Explicitly tells when to use: 'review what you're monitoring before adding more or to find an id to cancel.'

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

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

Annotations are all false, providing no safety or side-effect insight, so the description carries the full burden. It discloses rate limiting ('5 per identifier per day'), the claim_token flow for anonymous filing, that it's free and doesn't count against quota, and that the team reads digests daily — all meaningful behavioral context beyond structured fields.

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

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

Although longer than typical descriptions, every sentence adds necessary guidance: when to use, scope exclusions, message crafting, token mechanics, and rate limits. The structure flows logically from purpose to usage to follow-up, and the 'Not sure?' line proactively addresses ambiguity.

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 tool has no output schema and all parameters optional, so the description must explain the full contract. It covers return behavior (claim_token), how to check resolution status, rate limiting, and scope boundaries, making it fully usable without guessing. This is unusually complete given the tool's nuance.

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, but the description adds value by explaining how to frame the message ('don't paste the end-user's prompt') and by demonstrating the claim_token usage ('pipeworx_feedback({claim_token:"pwfb_…"})'). This goes beyond the schema's terse parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly delineates this from sibling tools by framing it as feedback rather than a query or research tool, and further clarifies scope by restricting to tools served by this Pipeworx connection.

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: for bugs, feature/data gaps, or praise, with concrete examples like 'wrong/stale data (bug)'. It also gives a clear exclusion rule: don't report issues from other MCP servers, and helps disambiguate by telling the agent to check Pipeworx tool names in the connection list.

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 basic annotations to disclose caching (5min-1h), data source (CF analytics-engine), privacy (no PII), and time-window semantics (hot vs steady-state). This provides rich behavioral transparency.

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

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

The description is moderately concise with a clear structure: core function, use cases, additional details. It is front-loaded with the main action. However, the bullet-point use cases could be slightly more compact.

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

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

The description covers purpose, use cases, data source, caching, and privacy. It mentions the three return components (top tools, top packs, total call volume) but does not specify the exact JSON structure. Given the tool's simplicity and lack of output schema, this is acceptable but not fully complete.

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

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

Schema description coverage is 100% with clear enum descriptions. The tool description reiterates the window options but does not add new parameter-level semantics beyond what the schema already provides. Thus, the description adds minimal value for 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 the tool returns trending data (top tools, packs, call volume) over configurable windows. It lists three specific use cases that distinguish it from query tools like ask_pipeworx or discovery tools like discover_tools.

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

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

The description lists three specific use cases (discovering hot data sources, confirming canonical tools, checking alignment). While it doesn't explicitly mention alternatives or when not to use, the context is clear and the use cases are well-defined.

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

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

Annotations confirm read-only, idempotent, non-destructive. Description adds behavioral details: Jaccard similarity threshold ≥0.30, partition filter dropping placeholder slugs, fill check against live CLOB depth with explicit trade advice.

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

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

The description is long but well-structured: overview, mode explanations, additional features, response format, fill check. Every sentence adds value, though some details (e.g., Jaccard threshold) could be slightly condensed.

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

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

For a complex tool with multiple modes and internal logic, the description covers all key aspects: mode behavior, semantic filtering, partition checks, fill check, and response structure. It references a sibling tool for custom sizing.

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

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

Both parameters are described in the schema; the description adds extensive context: what event and topic do, accepted formats (URLs), and internal logic (walks child markets, searches related events).

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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It explains three modes (no args, event, topic) and distinguishes from sibling tools focused on edges or fill risk.

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

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

The description provides explicit when-to-use guidance: no args for trending scan, event for a specific market (recommended), topic for cross-event scanning. It explains trade-offs and even when not to trade (realizable_edge_pp ≤ 0).

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 substantial detail: three response segments, caching (1h), Fed bets excluded from ranking, diagnostics for empty segments, and edge metrics (edge_pp_net, kelly_fraction, etc.). 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 long and detailed, front-loading purpose but then diving into extensive detail on segments and knobs. Could be more concise, but the structure is logical with clear sections and plain language.

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 9 parameters, no output schema, and complex behavior (three segments, diagnostics, caching, Fed notes), the description is remarkably complete. It explains all behaviors, filters, and edge cases, leaving little ambiguity for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond schema by explaining how parameters interact (e.g., min_kelly vs. min_partition_leg_kelly) and provides usage context for tradeable-edge knobs. Adds meaningful extra information.

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

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

The description opens with a clear verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by explicitly naming Pipeworx and its unique data disagreement approach.

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 it's built for 'what should I bet on today' and that agents can discover opportunities without paging hundreds of markets. It also explains knobs for filtering. Lacks explicit when-not-to-use guidance 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?

Annotations already indicate read-only and idempotent behavior. The description adds rich detail: the structure of tracked[], expired[], snapshot_dates[], and limitations like snapshot TTL and decay from daily closes. No contradictions.

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

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

The description is well-structured with a clear intro, response sections, and limitations. It is somewhat long but every sentence contributes value. Front-loaded with the key question.

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

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

Given the complexity (time-series, decay, expiration) and no output schema, the description thoroughly explains the response fields, including edge cases like gaps and median lifespan. It covers all necessary context.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds default values and clamp range (already in schema), but does not significantly enhance parameter understanding 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 'Edge persistence and decay telemetry' and explicitly states the tool answers 'how long has this edge existed and is it shrinking?'. It clearly distinguishes itself from sibling tools like polymarket_edges by focusing on time-series 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 implies when to use it (to assess edge freshness), but does not explicitly state when not to use it or offer alternatives. It contrasts fresh vs aging edges, providing good context.

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

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

Annotations already declare read-only and idempotent, but the description adds valuable behavioral details: walking the ladder, returning verdicts like clean/degraded/cannot_fill, and identifying forced directional risk. 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 well-organized with clear mode sections and emphasis, but it is somewhat verbose. Every sentence adds value, but could be tightened slightly without losing clarity.

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

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

No output schema, but the description enumerates all key return fields for both modes, covering top_of_book, VWAP, slippage, and risk metrics. Lacks explicit error handling details, but overall 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%, but the description adds significant meaning: explains the dual meaning of size_usd (spend vs target proceeds in single-market, settlement notional in basket), clarifies default side logic for baskets, and specifies clamp ranges beyond the schema's brief comments.

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 using live order-book depth, distinguishing between single-market and basket modes. It differentiates from siblings like polymarket_arbitrage by focusing on capturability of theoretical 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 instructs to use this tool before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500, and explains the risks of partial fills and uncapturable overround. Provides clear when-to-use guidance and rationale.

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

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

The description extensively covers behavioral traits beyond annotations: two modes, response fields, compatibility_warning cases, temporal alignment, and skipped counters. Annotations already signal read-only, open-world, idempotent, and non-destructive, and the description adds rich context 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 long but well-structured: overview, modes, response details, safety fields. Every sentence adds value, though it could be slightly more concise. The front-loading is effective with the main purpose immediately stated.

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

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

Despite no output schema, the description thoroughly explains the response structure: raw probabilities, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. This compensates fully for the missing output schema, providing complete guidance for an agent.

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

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

Schema coverage is 100% with descriptions, but the description adds value by listing the exact topic shortcuts, explaining that explicit tickers override topic-mapped ones, and providing examples. This clarifies usage 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question, and explains two modes (topic shortcuts and explicit tickers). It distinguishes itself from siblings like polymarket_arbitrage, which is single-venue. The verb 'spread' and resource 'cross-venue' are specific.

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

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

The description explains when to use: to compare prices across venues for equivalent events, and warns that real spreads are rarer than shortcuts suggest, with compatibility_warning indicating non-tradeable cases. It does not explicitly mention when to use sibling tools like polymarket_arbitrage instead, 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?

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description confirms these by stating it retrieves saved values and lists keys. It adds behavioral context about scoping to an identifier (anonymous IP, BYO key hash, or account ID), which is not in annotations.

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

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

Three sentences convey functionality, usage examples, and scoping without waste. The first sentence front-loads the core action. Every sentence adds unique value.

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

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

For a simple one-parameter read-only tool with full annotation coverage, the description covers what, when, how (parameter behavior), and context (scoping, partnering tools). No information is missing for effective use.

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

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

The input schema has 100% coverage with a description for the single parameter 'key'. The description explains omitting key lists all keys and relates key to previously saved values. This adds meaningful context beyond the schema's basic 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 explicitly states the tool retrieves a value saved via remember or lists all keys when omitted. It uses specific verbs ('retrieve', 'list') and resources ('value', 'keys'). It distinguishes from sibling tools like remember (save) and forget (delete) by mentioning them as partners.

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 concrete examples of when to use the tool (look up target ticker, address, research notes) and implies not to use it for re-deriving context. It guides pairing with remember and forget. However, it lacks explicit 'do not use when' statements.

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

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

Annotations declare readOnlyHint=true, implying no data modification. The description, however, explicitly states that setting mark_read:true 'flag[s] returned events read so the next call only shows newer ones', which is a mutation of the feed state. This is a direct contradiction between description and annotations, severely undermining transparency.

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

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

The description is remarkably concise: three sentences that cover purpose, return format, filtering, and polling behavior. Every sentence adds value with no redundancy. The paragraph is front-loaded with the core action and then efficiently expands on specifics.

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 and the absence of an output schema, the description adequately covers return fields (source, citation_uri, payload), all parameters (type, since, mark_read, unread_only, limit), and behavioral notes (polling, alternative endpoint). No critical information is missing for an agent to use this tool correctly.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: it explains the effect of mark_read (flags read to exclude from next call) and clarifies that unread_only returns events with null read_at. These details help the agent understand parameter behavior beyond the schema's terse descriptions.

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

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

The description starts with a clear verb ('Pull') and resource ('fired events from your subscription feed'), specifying return fields (source, citation_uri, raw event payload). It distinguishes itself from sibling tools like 'list_subscriptions' and 'subscribe' by focusing on alert retrieval, and even mentions an alternative REST endpoint for scripts/dashboards, clarifying its role within MCP.

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 'Polls work fine', indicating suitability for polling scenarios, and notes the same feed is available at a REST endpoint (GET registry.pipeworx.io/alerts.json) for scripts and dashboards, offering an alternative. However, it does not explicitly exclude usage in other contexts or compare with siblings for 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?

Beyond annotations (readOnly, idempotent), describes concrete behavior: parallel calls to SEC EDGAR, GDELT→GNews fallback, USPTO with soft-fail caveat. Also mentions return structure.

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 examples upfront, but slightly verbose. Every sentence adds value, though could be tightened slightly.

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

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

Fully self-contained: covers sources, fallback, parameter formats, return structure (changes grouped, total_changes, citation URIs), and caveats (USPTO sunset). No output schema, so description compensates completely.

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

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

Adds significant value over schema: provides examples for since (ISO/relative), explains value can be ticker or CIK, and clarifies type is limited to 'company'. 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?

Clear verb+resource: 'change feed for a company' with example queries. Explicitly distinguishes from sibling entity_profile, which provides static profile.

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

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

Provides explicit guidance: when to use (dynamic changes) vs when to use entity_profile (static profile). Also gives usage tips for the since parameter (e.g., 'Use "30d" or "1m" for typical monitoring').

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 write behavior (readOnlyHint=false) and idempotency (idempotentHint=true). The description adds valuable context: memory is scoped by identifier, authenticated users get persistent storage, anonymous sessions retain for 24 hours, and the tool is meant to be paired with recall/forget. 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 adding essential information. It is front-loaded with the primary purpose, immediately followed by usage guidance and behavioral details. 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?

Given the simplicity of the tool (2 required params, no output schema), the description fully covers purpose, instructions, behavioral aspects (persistence, scoping), and integration with sibling tools. Nothing essential is missing for correct invocation.

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

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

Schema coverage is 100% with descriptions for key and value. The description adds practical context for parameter usage: suggests naming conventions (e.g., 'subject_property') and clarifies that values can be any text. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool saves data for reuse, specifying the verb 'save' and resource 'key-value pair'. It distinguishes from siblings 'recall' and 'forget' by name, and provides concrete examples of use cases (resolved ticker, target address, etc.), making the purpose unmistakable.

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

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

The description explicitly states when to use: 'when you discover something worth carrying forward' and gives example scenarios. It pairs the tool with recall and forget, implying the intended workflow. It does not explicitly list when not to use, but the context is clear enough for an agent to decide.

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

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

Annotations already declare the tool safe (readOnly=true, destructive=false), but the description adds substantial behavioral context: it reveals internal cascading lookups, graceful degradation if GLEIF/OpenFIGI are unavailable, explicit labeling of unresolved identifiers instead of omitting them, and per-identifier source labeling. This goes well beyond the annotations and helps the agent anticipate partial failures.

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

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

The description is dense but well-structured: example queries first, then a clear purpose statement, followed by supported types and edge-case handling. While it is lengthy, every sentence provides useful detail, and the front-loading of examples aids comprehension. It could be trimmed slightly without losing value, but it is not bloated.

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 (two modes, multiple identifier sources, potential partial failures), the description is remarkably complete. It explains what identifiers are returned, how sources are attributed, behavior on unavailable upstream services, and the efficiency benefit of replacing multiple manual lookups. Even without an output schema, an agent can accurately predict the tool's behavior and 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?

The schema already covers 100% of the parameters with examples and clarifications. The description adds extra meaning by explaining what each entity type returns (e.g., company resolution includes CIK, ticker, LEI, FIGI) and how the `unresolved` field behaves. This enriches understanding beyond the schema's basic type/value descriptions, though the schema alone would be mostly sufficient.

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: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It lists concrete example queries (ticker, CIK, LEI, RxCUI) and distinguishes it from siblings by emphasizing this is the first step when you have a name but need an ID, which differentiates it from tools like entity_profile or compare_entities.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also enumerates supported types and input formats. However, it does not explicitly state when not to use the tool or name alternative tools, so it falls short of a 5 but provides clear context for selecting this tool over others.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds 'Probes each entity with ai_visibility_check' and describes return structure (ranked list with score, confidence, signal density). No contradictions.

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

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

Two sentences plus a usage example and return description. Every sentence is informative and no redundancy. Front-loaded with main 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?

No output schema, but description explains return format (ranked list with score, confidence, signal density). Parameter descriptions are clear. Minor gap: no mention of error handling or timeouts, but acceptable for this 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 value: first entity treated as 'subject', rest as competitors; context disambiguates common names; models: omit for default workers-ai. This is beyond schema.

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

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

Description clearly states 'Compare AI visibility across multiple entities side-by-side' with specific verb 'probes, ranks, surfaces'. Distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (likely different comparison).

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

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

Provides explicit use case: 'competitive AI-marketing audits' with example 'does Claude know about us as well as our competitors?'. No explicit when-not-to-use or alternatives, but context from sibling tools implies appropriate scope.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: 'Partial failures degrade gracefully', specific timeout (5-30s for bundlephobia), and that sources_failed will 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?

The description is reasonably concise given the tool's complexity. It front-loads the main purpose and organizes information logically (what it does, when to use, limitations, behavior). Could be slightly more compact but still effective.

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

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

Given the complexity of the tool, no output schema, and comprehensive annotations, the description covers all necessary aspects: purpose, inputs, behavior on failure, ecosystem scope, and output structure. It leaves no major gaps for an agent to understand how to use this tool effectively.

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

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

Schema coverage is 100% with good descriptions for both parameters. The description adds clarity that scoped packages are accepted and reiterates the default version behavior, but does not add entirely new semantic information beyond what the schema already provides.

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

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

The description clearly states it's a composite check for npm packages, fanning out across deps.dev and bundlephobia. It uses specific verbs ('Scan Dependency') and resources ('npm package', 'deps.dev', 'bundlephobia'), and is distinct from all sibling tools which cover other domains like research, betting, or tool discovery.

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

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

Explicitly states when to use it ('is X safe / popular / small' or 'what does adding lodash cost me') and provides a clear alternative for non-npm ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly').

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds minor context about return fields (name, category, href) and the database authority, but doesn't disclose additional behavioral traits like pagination or rate limits, which would add value beyond annotations.

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

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

The description is two sentences, front-loaded with the core functionality. Every sentence adds value without redundancy or fluff. Extremely efficient.

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

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

For a simple search tool with no output schema, the description covers the database, searchable entities, and return fields. Minor gaps: no mention of pagination, default limit, or ordering, but overall sufficient for basic usage.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description reinforces the free-text nature and 'Keyless' hint, but adds no new semantic details beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool searches SGD for genes and other entities via free-text query, specifying the authoritative resource and entity types. It distinguishes itself from sibling tools like get_gene by being keyless (free-text) versus key-based retrieval.

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

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

The description implies usage for free-text searches via 'Keyless' but does not explicitly state when to use this tool versus alternatives like get_gene or give when-not scenarios. The guidance is vague, leaving the agent to infer 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?

Discloses key behaviors beyond annotations: uses BGE-base-en embeddings, cosine over 500-char overlapping windows, 200K char cap with truncation flag, returns offsets and similarity scores. Annotations only provide readOnly, idempotent, openWorld hints; description adds rich operational detail.

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 a single paragraph but well-structured: purpose sentence, use case, technical details. Could be slightly tighter but no waste; front-loaded with key action.

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

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

Given complexity of semantic search, large text handling, and no output schema, description is thorough: explains truncation, embedding model, window size, offset purpose, and pairing with sibling tool. Covers all aspects an agent needs to use the tool correctly.

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

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

Schema coverage is 100% and description adds value: for text states max ~200K chars, for query gives natural-language examples, for limit states range 1-20 with default 5. This clarifies usage beyond schema descriptions.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and contrasting with whole-document usage.

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 suggests pairing with ask_pipeworx_grounded. Lacks explicit when-not-to-use or alternatives for records that fit, 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?

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds behavioral context: returns a new subscription id, requires OAuth account, details on delivery channel behavior (webhook signing, auto-disable after 10 failures, SMS cap). No contradiction with annotations.

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

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

The description is lengthy but well-structured, front-loaded with the main purpose and then expanding into details. While every sentence adds value, it could be more concise by grouping or using bullet points, but the density of information is high.

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

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

Given 3 parameters with nested objects, multiple types, no output schema, and 100% schema coverage, the description compensates fully. It covers examples, constraints, prerequisites, return value, and delivery behavior. The tool is complex, and the description leaves no gaps.

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

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

Schema coverage is 100%, but the description adds significant value beyond the schema. For 'type', it explains each enum value with real examples. For 'params', it provides per-type JSON structures. For 'delivery', it adds behavioral details (e.g., webhook signing, SMS verification requirement, cap).

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 creates a proactive monitoring subscription to a live-data event stream, using the verb 'Create' and specifying the 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 provides explicit guidance on when to use the tool (proactive monitoring), supported types with detailed examples, delivery channels, prerequisites (OAuth account, phone verification for SMS), and constraints (SMS cap, webhook auto-disable). No alternatives explicitly named, but context is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context that it returns category-bucketed example questions with exact tool+argument shapes from a live catalog, and that passing a topic focuses the results. No contradictions.

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

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

The description is well-structured with trigger phrases upfront, followed by a clear explanation of output and usage. While slightly long, every sentence adds value, and it is front-loaded with key purpose and usage.

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

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

Given no output schema, the description fully explains what the tool returns (category-bucketed example questions with tool+argument shapes) and how to use it. It also mentions the live catalog and meta-tools, making it complete for an onboarding tool.

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

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

Schema coverage is 100% with one optional parameter. The description adds meaning beyond the schema by listing example values for topic (finance, pharma, etc.) and stating that omitting topic gives a cross-category spread, which aids understanding of parameter behavior.

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

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

The description clearly states the tool is an onboarding entry point for new agents to learn what questions to ask, explicitly listing trigger phrases and positioning it as the first tool to use. It distinguishes from siblings like ask_pipeworx and discover_tools by specifying it returns example questions with tool+argument shapes.

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

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

The description provides clear guidance: use this tool first when unsure about Pipeworx capabilities, call with no arguments for full spread or pass a topic to focus. It implicitly tells when to use it (first) and what it's for, though it doesn't explicitly state when not to use alternatives.

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

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

The description adds behavioral details beyond annotations: ownership enforcement and deactivation (not deletion). Annotations already indicate destructiveHint=false, but the description elaborates meaningfully. No contradiction with annotations.

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

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

Two sentences with no wasted words. The action is front-loaded and each sentence adds necessary context. Highly efficient.

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

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

No output schema exists, but the description explains the effect of the tool (deactivation) and the persistence of historical events. It does not mention return value or error cases, but for a simple cancellation tool this is adequate.

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

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

Schema coverage is 100% and the parameter 'id' is described in the schema. The description does not add additional meaning beyond what the schema already provides, meeting the baseline of 3.

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

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

The description clearly states the action ('Cancel a subscription by id') with the specific resource (subscription) and the required identifier. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description mentions ownership enforcement and explains the deactivation behavior, giving clear context for when to use. It does not explicitly state when not to use or mention alternatives, but the context is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description goes far beyond this by explaining the two distinct execution paths, the exact meaning of each verdict (especially the critical distinction between 'could_not_verify' and 'unsupported'), and the presence of verification_error. It warns callers not to treat 'could_not_verify' as evidence, which is crucial behavioral context not inferable from annotations.

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

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

The description is long but well-structured: it front-loads the purpose with trigger phrases, then covers routing, return format, and critical caveats. Every sentence contributes useful information, though some redundancy exists (e.g., listing six paraphrases of 'verify'). The length is justified by the tool's 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?

Given no output schema, the description thoroughly explains return values (verdict list, actual value, citation, reasoning), error semantics, and the 'unsupported' case. It even explains that the tool replaces multiple sequential calls, giving the agent a full mental model of its behavior. This is complete for a tool of this 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%, so both parameters are already well-documented. The description adds valuable context for tolerance_pct (override behavior, default, and use case for hallucination detection) and gives concrete claim examples. This exceeds the baseline for high coverage, but does not fully compensate for missing output schema details.

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

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

The description clearly identifies the tool as natural-language claim verification with specific trigger phrases ('Is it true that…', 'fact check'). It distinguishes between two processing paths (SEC EDGAR fast path for company-financial claims vs. grounded pipeline for everything else), which differentiates it from siblings like ask_pipeworx_grounded or compare_entities. The verb 'verify' plus resource 'claim' is specific and 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 states 'Use whenever the agent needs to check whether something a user said is factually correct' and provides clear trigger examples. It explains the structured vs. grounded routing logic, but does not explicitly name alternative tools or say when NOT to use it. Still, the guidance is strong enough to steer an agent correctly.

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