Mychem

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

The description adds significant behavioral context beyond annotations: default model (Workers AI Llama-3.3-70b, free), BYO key for Anthropic with direct billing, and return structure (per-model objects plus combined view). Annotations already declare readOnly, openWorld, idempotent, non-destructive; description agrees and elaborates.

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 with a clear front-loaded purpose, followed by default behavior, optional key explanation, return structure, and use cases. 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?

The description covers all key aspects: what it does, input parameters (with defaults and optionality), output structure (per-model and combined), pricing/free model, and use cases. No output schema exists, but the description adequately describes return fields.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by explaining default model behavior, the optionality of _apiKey (only needed for anthropic), and the return format (score, confidence, signals, raw_response). This goes beyond the schema's 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 uses specific verbs 'probe' and 'score' with clear resource 'LLMs for what they know about a business/brand/product/topic'. It distinguishes from sibling tools like 'ask_pipeworx' by focusing on AI visibility scoring rather than general Q&A or entity profiles.

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 cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It does not provide explicit when-not-to-use or alternatives, but the context signals and sibling list help infer that this tool is specialized for visibility checks rather than general queries.

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, open-world, idempotent, non-destructive. The description adds operational detail: routes to 5008 tools, returns structured answers with pipeworx:// citation URIs, and mentions speed ('one fast call').

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

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

The description is long but well-structured with bold emphasis, clear sections (prefer, use, step up, examples). Slightly verbose but effectively organized.

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

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

Given the lack of an output schema, the description sufficiently explains what the tool returns. It covers usage, alternatives, and typical queries. Could mention output format, but citations are noted.

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 each alias described. The description adds context by listing example questions and clarifying the scope of acceptable queries, going beyond the schema.

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

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

The description clearly states the tool answers factual questions with authoritative structured data, listing many domains. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, specifying when to use each.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', with specific when-to-use guidance and when to step up to alternatives (grounded, deep_research). Provides concrete examples of queries.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: it is a full working router, falls back to nothing (self-contained), and details the source-preference ranking experimental improvement, complementing the annotations without contradiction.

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

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

Two concise sentences front-loaded with key information: beta status, identical nature, experimental improvement, and usage guidance. No 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?

The description covers the tool's purpose, experimental feature, usage instructions, and relationship to the stable version. While it lacks output schema details, it references the same response shape, which suffices given the stable counterpart. The number of tools and argument structure are mentioned for completeness.

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

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

With 100% schema coverage, the description adds context that the tool is a router accepting a natural language question, and notes the same response shape as the stable version. This enhances understanding beyond the schema's alias 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 it is a beta version of ask_pipeworx, an identical universal router with the same 5,008 tools and arguments, but with experimental routing improvements. It distinguishes itself from the stable version and other siblings.

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

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

Explicitly directs to use it like ask_pipeworx when wanting the newest routing, and explains results are compared against the stable router to decide merges. Provides clear context for when to use this variant.

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

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

Description adds behavioral context beyond annotations: costs one extra LLM call, picks from 5,008 tools across 1,318 sources, returns refusal reasons. No contradiction with annotations.

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

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

Two concise sentences followed by a structured list of return format and refusal reasons. Front-loaded with key purpose, no wasted words.

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

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

Despite no output schema, description fully specifies return structure with fields and refusal reasons, compensating well. Covers all necessary context for the tool's complexity.

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

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

Schema coverage is 100% with all 6 parameters described. Description restates alias information and notes 'natural language' for the question parameter, but adds limited 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?

Description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' and explains it extracts answer only from tool result, returning explicit refusals. Differentiates from sibling 'ask_pipeworx' by noting cost and suitability.

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 when to use (answers to be quoted, cited, acted on, high-stakes domains) and when to prefer alternative ('prefer ask_pipeworx for casual lookups'), providing clear decision criteria.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds rich detail: status codes (low_confidence_match, market_closed_or_inactive), tradeability warnings, cancellation rule parsing, parent event extraction, and safety short-circuits. This significantly exceeds what annotations alone provide.

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

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

The description is long but well-structured with clear sections (classifiers, fan-out examples, response shapes, etc.). It is front-loaded with purpose and usage. While some redundancy exists, every section provides necessary detail for correct 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?

No output schema exists, so the description carries full burden. It thoroughly explains all response fields (market, analysis, evidence, resolver, parent event, news, safety flags) and edge cases (low confidence, closed markets, illiquid spreads, cancellation rules). This is complete for a complex tool with many conditional behaviors.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying input formats for 'market' (slug, URL, question) and elaborating on 'depth' and 'include_raw' with practical usage notes (quick vs thorough, response size 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 clearly states the verb-resource pair ('Research a Polymarket bet by pulling the relevant Pipeworx data for it') and distinguishes the tool from siblings by focusing on single-bet research with classification and fan-out, unlike polymarket_edges or arbitrage which serve different purposes.

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

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

The description explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides extensive category-specific examples. However, it does not directly contrast with sibling tools, though the context implies when to use this 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 no behavioral details beyond what annotations provide, but does not contradict them.

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

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

Two sentences: first defines action and resource, second elaborates on id formats and return content. No unnecessary words.

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

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

For a simple read-only fetch tool with comprehensive annotations, the description fully explains what the tool does and returns. No missing gaps for agent 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%. Description adds examples for 'id' parameter and mentions return fields, but these are minor additions beyond the schema descriptions.

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

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

Describes specific verb 'Fetch' and resource 'full aggregated annotation for a single chemical/drug by id.' Clearly distinguishes from sibling tools like 'entity_profile' or 'resolve_entity' which are more generic.

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

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

States typical id type (InChIKey) and alternative ids (DrugBank, ChEMBL, etc.), guiding when to use. Lacks explicit when-not-to-use or direct sibling alternatives, but context is clear.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint=true, and destructiveHint=false. The description adds significant context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URI returns. 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 somewhat long but well-structured, front-loaded with example queries. Each sentence adds value, explaining data sources, sorting, and replacement of sequential lookups. Minor redundancy could be trimmed, but overall efficient.

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

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

Given the tool's complexity and no output schema, the description provides a solid overview of inputs, behavior, and outputs (paired data + citation URIs). It covers both entity types and sorting. Some details like exact metrics per type could be clearer, but sufficient 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%, providing baseline 3. The description adds meaningful details: explains that type='company' pulls financials with specific fiscal year handling, and type='drug' pulls adverse event and trial data. It also clarifies values constraint (2-5 items) with examples. This raises the baseline to 4.

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

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

The description clearly states that the tool performs side-by-side comparisons of 2-5 companies or drugs, specifying data sources and metrics. Example queries like 'Compare X and Y' and 'which is bigger' show the intended use, and it distinguishes itself from sibling tools like entity_profile by noting it replaces sequential lookups.

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

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

The description explicitly advises to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides example triggers. While it does not explicitly list when not to use, the guidance is strong and contextually 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 indicate read-only, open-world, idempotent, non-destructive. Description adds extensive behavioral detail: returns a findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[] for unanswered facets, contradictions[], hop field, citation_uri, semantic excerpting of large records, and expected response times (15-90s). 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 but well-structured and front-loaded with critical info (account requirement, alternative). Every sentence adds distinct value. Slightly verbose but appropriate 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?

Given the tool's complexity and lack of output schema, the description thoroughly explains what the tool does, its output format (findings packet with evidence, gaps, contradictions, citations), iteration behavior, timing, and scope limitations. No gaps in essential information.

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

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

Schema covers 100% of parameters. Description enriches both: depth explains quick (3 facets, single hop), standard (5+gap recovery+contradictions), thorough (8+iterative+contradictions, paid). question states natural language, broad/multi-part fine. Adds meaning beyond schema.

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

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

The description clearly states it performs grounded multi-source research across 1,318 structured data sources, not open-web search. It distinguishes from sibling ask_pipeworx by specifying that this tool is for broad/multi-part questions over structured data, while ask_pipeworx is for single lookups or breaking news.

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

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

Explicitly tells when to use deep_research vs ask_pipeworx, including guidance for breaking news topics. Also mentions account requirements (free sign-in via GitHub, paid for 'thorough' depth) and that if not signed in, ask_pipeworx works on every tier.

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, destructiveHint. The description adds useful behavioral context: 'each result is ready to call directly, no second schema lookup needed' and mentions returned content (names, descriptions, schemas with examples). 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 comprehensive yet front-loaded with the core purpose. It could be slightly trimmed but every sentence adds value, making it appropriately sized.

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

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

Given the tool's complexity (6 params, no output schema, many siblings), the description covers purpose, behavior, usage guidance, and return format adequately. It compensates for lack of output schema by describing results as 'top-N most relevant tools with full schemas.'

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

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

Schema description coverage is 100%, so baseline is 3. The description reiterates the query parameter accepts aliases and natural language, which is already in the schema, adding no additional value.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and explains the return format, distinguishing it from sibling tools which are domain-specific (e.g., chem, entity_profile).

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

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

Explicitly advises to 'Call this FIRST when you have many tools available,' providing clear context for when to use it. It doesn't explicitly state when not to use it, but the guidance 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 and idempotentHint. The description adds significant behavioral context: it fans out across multiple APIs (SEC, XBRL, USPTO, news, GLEIF), specifies what each returns, acknowledges the USPTO PatentsView API sunset with soft-fail behavior, and notes that names are not supported. 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 informative and front-loaded with example queries, but it is somewhat long. However, every sentence adds value, and the structure flows logically from purpose to details. A minor reduction for verbosity.

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

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

Given the tool's complexity (multi-source aggregation) and the absence of an output schema, the description is remarkably complete. It enumerates all returned components (CIK, filings with URIs, fundamentals sorted by period_end, patents with sunset note, news via fallback, LEI). It also covers limitations, making it sufficient for an agent to understand the tool's capabilities.

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

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

Schema coverage is 100%, but the description adds essential meaning beyond the schema. It explains that 'type' is currently limited to 'company', gives examples for 'value' (ticker or zero-padded CIK), and explicitly states that names are not supported. This helps the agent avoid errors.

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

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

The description clearly states that the tool provides a 'full cross-source profile of a US public company' in one parallel call. It gives specific example queries and lists the exact data returned, making the purpose unmistakable. It also differentiates from sibling tools like resolve_entity by noting that names are not supported here.

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

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

The description explicitly advises 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views. It also tells the agent when not to use it (if only a name is available, use resolve_entity first). This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds context about clearing sensitive data and when to use, which complements the annotations without contradiction.

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

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

Two concise sentences: first states core action, second provides usage scenarios. Every word 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 tool with one parameter, no output schema, and clear annotations, the description covers purpose, usage, and pairing. Nothing essential is missing given the tool's simplicity.

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

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

Schema coverage is 100% with parameter 'key' described as 'Memory key to delete'. The description does not add additional meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool deletes a memory by key, using specific verb 'Delete' and resource 'previously stored memory'. It distinguishes from sibling tools 'remember' and 'recall' by implying it's the deletion counterpart.

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 (stale context, task done, clear sensitive data) and suggests pairing with 'remember' and 'recall'. Does not explicitly state when not to use, but the context is clear enough for an agent.

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, covering safety. The description adds value by describing the crawling, extraction, and output format, which goes beyond the annotations.

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

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

The description is three sentences plus a concise bullet list, front-loaded with the core purpose, then details and use cases. Every sentence adds value with no redundancy.

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

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

For a simple tool with 2 params, no output schema, and strong annotations, the description covers purpose, use cases, process, and output format. Minor gaps: no mention of error handling or prerequisites (e.g., URL reachability), but overall sufficient.

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

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

Schema coverage is 100%, with both parameters well-described in the schema. The description adds no further detail for max_links and only a minor example for url, so it does not significantly enhance 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 clearly states the verb 'generate', the resource 'llms.txt file', and the actions: fetch, extract, emit. It distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on llms.txt generation, not just visibility 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 provides explicit use cases (client indexing, own project, competitor auditing), giving clear context. However, it does not explicitly state when not to use this tool or mention alternative sibling tools for similar tasks.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to restate safety. It adds value by detailing the return fields and mentioning 'active' vs 'include_inactive', but no additional behavioral traits like scope or pagination.

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

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

Two sentences, front-loaded with purpose, then usage guidance. No filler or redundancy. Every sentence earns its place.

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

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

For a list tool, the description covers purpose, returned fields, usage context, and parameter semantics. No output schema exists, but the description provides the return fields. It lacks details on ordering or pagination, but those are not critical for this tool's simplicity.

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

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

Schema coverage is 100%, so the parameter is well-documented in the schema. The description adds marginal context by implying the default behavior (active only) through the phrase 'active subscriptions' and the parameter name.

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 ('list'), the resource ('the caller's active subscriptions'), and specifies the returned fields (id, type, etc.). This distinguishes it from sibling tools 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?

The description provides explicit use cases: 'review what you're monitoring before adding more or to find an id to cancel.' It suggests when to use but does not explicitly mention when not to use or name alternatives, though siblings are available.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds context about the returned data fields but does not provide additional behavioral traits beyond what annotations cover. No contradiction.

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

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

Single sentence, no wasted words, front-loaded with the verb 'Returns'. Highly concise and well-structured.

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

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

Given no output schema or parameters, the description is fairly complete, listing the exact returned fields (compound count, sources, versions). It could mention output format but is adequate for a simple metadata 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?

With zero parameters and 100% schema coverage (trivially), the baseline is 4. The description adds full meaning by explaining what the tool returns, compensating for the empty 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 returns MyChem.info build metadata, including specific fields like compound count, annotation sources, and versions. It uses a specific verb ('Returns') and resource, distinguishing it from sibling tools.

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

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

The description implies usage for retrieving metadata but does not explicitly state when to use this tool versus alternatives or when not to use it. No exclusion criteria or alternative tools are mentioned.

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

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

The description discloses important behavioral traits beyond annotations: rate-limited to 5 per identifier per day, free, and doesn't count against quota. Annotations are minimal (no readOnly, etc.), so this added context is valuable for agent behavior planning.

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—five sentences with no wasted words. It front-loads the purpose, then covers usage, constraints, and quotas in a logical order. Every sentence earns its place.

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

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

Given the tool's simplicity (no output schema, 3 parameters with full schema descriptions), the description is complete. It covers purpose, usage guidelines, behavioral traits, and parameter usage nuances, leaving no gaps.

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

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

Schema description coverage is 100%, so the schema already documents each parameter well. The description adds value by explaining what not to include in the message (e.g., 'don't paste the end-user's prompt') and by reiterating the types in context, which helps the agent form better messages.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('send feedback') and resource ('Pipeworx team'), and it naturally distinguishes itself from all sibling tools, as none are for feedback.

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 scenarios: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also includes what not to do: 'don't paste the end-user's prompt.' This gives clear guidance for selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining the data source (CF analytics-engine), the lack of PII, and the caching behavior (5min-1h depending on window), providing useful 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?

The description is concise and well-structured: a one-sentence summary followed by bullet-point use cases and a note on data source and caching. 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?

For a simple tool with one optional parameter and no output schema, the description covers what it returns, use cases, caching, and data source. It lacks an explicit return format, but the listed outputs (top tools, top packs, total call volume) are sufficient for an AI agent to understand the tool's functionality.

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 single 'window' parameter fully described in the schema via enum and description. The tool description adds a slight nuance about shorter vs longer windows, but this is minimal. Baseline 3 is appropriate.

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

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

The description starts with a clear verb ('Returns') and states the specific resource: top tools, top packs, and total call volume from other AI agents on Pipeworx. While it does not explicitly differentiate from sibling tools like 'discover_tools', the purpose 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 provides three explicit use cases in bullet points: discovering hot data sources, confirming canonical tools, and aligning use cases. It does not list when not to use the tool or suggest alternatives, but the guidance is clear and helpful.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: details on algorithms (monotonicity, partition-sum), semantic anchor with Jaccard similarity, placeholder filtering, fill check against live CLOB depth, and the response structure. No contradictions.

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

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

The description is long but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It is front-loaded with the core purpose and mode selection. Some redundancy exists, but the detailed explanation is warranted for a complex tool.

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 provides a thorough picture: it explains both input modes, internal logic, filtering, fill check, and even mentions related tool for custom sizing. It covers default behavior, edge cases, and response fields, making it fully self-contained.

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

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

Schema description coverage is 100% with brief descriptions for event and topic. The tool description expands greatly, explaining event mode walks child markets and performs checks, topic mode searches related events, and default behavior with no args. This adds crucial meaning beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It specifies three modes (trending_scan, event, topic) and distinguishes from sibling tools like polymarket_fill_risk at the end. This provides specific verb+resource with 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?

The description gives explicit guidance on when to use each mode: no args for trending_scan, event for a specific market, topic for cross-event scanning. It also explains when not to trade (realizable_edge_pp ≤ 0). However, it does not explicitly contrast with sibling tools like polymarket_edges or polymarket_edge_tracker, which would strengthen the guidelines.

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 safe, read-only, idempotent behavior. The description adds extensive behavioral details: caching at KV level keyed to all knobs, output structure (by_segment, diagnostics), model formulas, edge calculations, and parameter effects. 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 but well-structured, with clear sections for model families, response structure, knobs, and caching. It front-loads the purpose. However, some redundancy exists (e.g., repeat of 'Tradeable-edge' details). It earns its length given 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?

With no output schema, the description fully explains the response structure (by_segment, diagnostics, Fed note, etc.), model logic, and caching. It covers all aspects needed for an agent to understand call behavior and interpret results.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances parameter meaning by explaining context (e.g., 'Tradeable-edge filter', 'Partition arbs always return kelly_fraction_half=0'), going beyond the schema's type and description fields.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific verbs and resources, and the detailed segmentation into model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) distinguishes it from potential sibling tools like polymarket_arbitrage.

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

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

The description provides usage context ('Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets'), which implies when to use it, but it does not explicitly state when not to use it or compare to alternatives like polymarket_arbitrage. Exclusions are only implicit (e.g., Fed bets are excluded from ranking).

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, openWorld, idempotent, non-destructive), the description details response structure (tracked[], expired[], snapshot_dates[]), limitations (60-day TTL, daily closes), and clarifies that decay numbers are computed from daily closes of edge_pp_net, not intraday.

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 densely packed with useful information and front-loaded with the core purpose. Though relatively long, each sentence adds value with no fluff, balancing completeness and efficiency.

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

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

Given no output schema, the description fully covers return values (tracked[], expired[], snapshot_dates[]) and limitations (history depth, decay computation). It provides all necessary context for an agent to understand tool behavior and output.

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

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

Schema coverage is 100% for both parameters. The description adds context: default and max values for 'days', default for 'window', and explains that 'window' refers to snapshot family. This goes beyond the schema's minimal 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 it provides edge persistence and decay telemetry from polymarket_edges snapshots, answering a specific question about edge age and trend. It distinguishes itself from sibling tool polymarket_edges by focusing on time-series analysis rather than current snapshots.

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

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

The description explains when to use the tool by contrasting fresh vs. old edges ('the latter is wide for a reason nobody is willing to take'). It implies usage context for assessing edge longevity but does not explicitly state when not to use or list alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the behavioral burden is reduced. The description adds significant context: it walks the order-book ladder, returns specific verdicts (clean, degraded, cannot_fill), and warns about partial basket fills. However, it does not explicitly state what happens if both market and event are omitted, nor does it detail all edge cases.

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

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

The description is dense and informative but could be better structured. It flows as a continuous paragraph without bullet points or clear separation of modes and return fields. While every sentence adds value, readability is somewhat compromised. Score 3 for moderate 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?

Given the tool's complexity (two modes, 4 parameters, no output schema), the description is fairly complete. It enumerates all return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and explains derived metrics like capture_ratio and forced_directional_risk. Minor missing details (exact types of return values) prevent a 5.

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

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

Schema coverage is 100% with descriptions, baseline is 3. The description adds value by explaining how size_usd is interpreted differently per mode (max spend vs target proceeds vs settlement notional) and the default for side in basket mode ('auto'). This additional context justifies a 4.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges, making the purpose unambiguous.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the consequence of not using it (partial fills leading to unhedged directional positions) and implies alternatives such as smaller trades or direct use of 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=true, idempotentHint=true, destructiveHint=false, so the tool is safe. The description adds extensive behavioral detail: two modes, response structure (leg-by-leg prices, spreads, safety fields), and edge cases (compatibility_warning types, temporal alignment, skipped pairs). This goes far beyond the annotations, giving the agent a full picture of what the tool does and when results should be trusted.

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

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

The description is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS), making it easy to parse. It front-loads the core purpose. However, it is somewhat verbose, with detailed technical explanations that could potentially be summarized. Every sentence adds value, but a slightly tighter edit could improve efficiency without losing meaning.

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

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

No output schema exists, so the description must fully explain return values. It does so comprehensively: per-venue leg prices, spread array, compatibility_warning with two cases, temporal_alignment fields, and skipped pair counters. Given the tool's complexity (two modes, multiple error states, cross-venue comparison), this description is remarkably complete, leaving no major gaps for an AI agent to misunderstand.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds meaning by explaining the two operational modes ('topic' vs explicit), providing concrete examples ('fed', 'btc'), and detailing how each parameter behaves (overrides, auto-fetching). This adds moderate value beyond the schema, clarifying the interaction between parameters and the response fields.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' with specific verb+resource. It distinguishes from sibling tools like 'polymarket_arbitrage' by focusing on cross-venue spreads, and explains two distinct modes (topic shortcuts and explicit pairings), leaving no ambiguity about the tool's function.

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

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

The description provides clear context for when to use the tool, including safety fields that indicate when spreads are meaningless (incompatible bet shapes, temporal misalignment). It implicitly guides away from use when compatibility warnings are triggered, though it does not explicitly name alternative tools. The pre-mapped topic caveat ('most pre-mapped topics return compatibility_warning today') is helpful but could be more directive.

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, etc. The description adds value by explaining the return type (aggregated hits with cross-references) and the variety of accepted query formats, which is beyond what annotations provide.

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

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

The description is two sentences, front-loaded with the main action, and every sentence adds essential information. No redundancy or 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 explains the return type qualitatively but lacks specifics on the response structure (e.g., JSON format, field names). It is adequate but could be more detailed.

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

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

Schema description coverage is 100%, and the description adds examples for the 'query' parameter (plain name, InChIKey, fielded query) and mentions 'size' and 'fields' implicitly. This enhances 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 clearly states the tool searches MyChem.info for drugs and chemical compounds, accepts multiple query formats, and returns aggregated hits with cross-references. It provides specific verbs and resources but does not differentiate from sibling tools like 'chem'.

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

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

The description says 'Use this to resolve a drug name into structured identifiers,' providing clear guidance on when to use. However, it lacks explicit when-not-to-use instructions or alternatives among sibling tools.

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

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

Annotations provide readOnlyHint=true and idempotentHint=true, and the description adds value by specifying scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and pairing with remember/forget. No contradiction with annotations.

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

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

The description is three sentences with no wasted words. It front-loads the purpose, provides usage guidance, and adds contextual completeness efficiently.

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

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

For a tool with 1 optional parameter and no output schema, the description fully explains the dual behavior (single retrieval vs. listing), scoping, and relationship to sibling tools. It is complete.

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

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

Schema coverage is 100% and already describes the parameter 'key' as 'omit to list all keys'. The description repeats this without adding new semantics. 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 explicitly states the verb ('retrieve') and resource ('value previously saved via remember'), and distinguishes from siblings ('list all saved keys (omit the key argument)'). It clearly differentiates from remember and forget by name.

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: 'look up context the agent stored earlier' and 'without re-deriving it from scratch'. It provides context on scoping and pairing with remember/forget, but does not explicitly state when not to use or provide alternatives.

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

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

The description adds behavioral context beyond annotations: describing that mark_read flags events as read affecting future calls, and that polling is suitable. However, there is a contradiction with the idempotentHint annotation because mark_read is a side effect.

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

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

The description is concise with four sentences, each serving a purpose: stating purpose, listing key fields, explaining parameters and side effects, and noting polling and alternative access. 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 covers key returned fields (source, citation_uri, raw payload) and explains mark_read's effect. It mentions filtering and polling. Minor omissions: limit parameter and unread_only are not described in text, but schema covers them.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the effect of mark_read and mentioning filtering options, as well as specific returned fields, which goes beyond the schema descriptions.

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

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

The description clearly states the tool pulls fired events from a subscription feed and returns alerts with source, citation_uri, and raw payload. It is specific about the action and resource, but does not explicitly distinguish from sibling tools like list_subscriptions or recent_changes.

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 filtering by type and since, the effect of mark_read, and that polling works fine. It also provides an alternative endpoint for scripts/dashboards. However, it does not explicitly state when not to use this tool or compare to alternatives.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds significant behavioral context: fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail due to API sunset, and return format (changes[] grouped by source). No contradictions.

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

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

The description is thorough and well-structured, with examples front-loaded and technical details following. Could be slightly more concise, but every sentence serves a purpose and 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?

For a complex tool with multiple data sources, fallback behavior, and no output schema, the description is remarkably complete. It covers source specifics, edge cases (soft-fail, fallback), and return structure (grouped changes, total_changes, citation URIs). No gaps identified.

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

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

Schema coverage is 100% with descriptions, but the description adds meaning beyond schema: clarifies 'since' formats (ISO date, relative shorthand like '7d', '30d'), that 'value' accepts ticker or CIK, and provides typical monitoring hint. This extra guidance enhances agent 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?

Description starts with numerous example queries ('What's new with X', 'latest on Y'), then clearly states the tool provides a change feed for a company over a window, fanning out to multiple sources. It explicitly distinguishes itself from entity_profile, making purpose and differentiation 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?

Provides explicit when-to-use examples and contrasts with sibling tool entity_profile ('Use entity_profile instead when you want the static profile'). Also gives usage guidance 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?

Discloses key-value pair storage, scoping by identifier, and persistence differences (authenticated vs. anonymous, 24-hour retention). Adds value beyond annotations which already indicate idempotent and non-destructive traits.

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

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

Four sentences, front-loaded with purpose, no redundant information. Every sentence earns its place with concise wording.

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 2-param tool with no output schema or nested objects, the description fully covers purpose, usage, behavior, and parameters. 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 covers 100% of parameters with descriptions. Description adds examples for key values (e.g., 'subject_property') and clarifies value as 'any text', providing incremental context.

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

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

Description clearly states the tool 'save data the agent will need to reuse later' with specific verb and resource. It distinguishes from siblings like 'recall' and 'forget' by pairing.

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 ('when you discover something worth carrying forward') and provides exclusions (scope, persistence). Pairs with recall and forget, giving alternatives.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already indicate safe, idempotent, read-only behavior. The description adds that it cascades through several lookup endpoints internally, replacing 2-3 manual lookups, which provides useful 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?

The description is somewhat lengthy but well-structured: it starts with query examples, then states the primary use case, then details supported types. Every sentence adds value, and it is not overly verbose for the complexity of the tool.

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 sufficiently explains return values for each type. It covers internal behavior (cascading lookups) and placement in the tool list (first step). The sibling list includes entity_profile, which suggests a complementary tool, providing enough context for an agent to decide when to invoke this tool.

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

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

The input schema covers 100% of parameters with descriptions. The description adds rich meaning for each parameter value (e.g., company accepts ticker, CIK, or name; drug accepts brand or generic) and explains the returned fields per type, compensating for the lack of an output schema.

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

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

The description explicitly states the tool's purpose: resolve a user-spoken name to a canonical identifier, with concrete examples like 'What's the ticker for…'. It clearly distinguishes itself as the first step before using other tools that require IDs, and lists supported entity types (company, drug) and their outputs.

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 when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It details what the tool accepts and returns for each type, but does not explicitly mention when not to use it or compare to sibling tools like entity_profile, though 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 safe, idempotent, non-destructive behavior. Description adds that it probes each entity with ai_visibility_check and returns ranked list with score, confidence, signal density, which is valuable context 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, front-loaded core function, efficient process description, and concrete use case. No redundancy or 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?

Tool has 4 params (1 required), no output schema, but annotations are comprehensive. Description explains output structure, gives usage examples, and covers behavioral aspects sufficiently for the complexity.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning by explaining first entity treated as 'subject' for narrative, clarifies count 2-8, and gives example for context. Adds value beyond schema.

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

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

Description clearly states tool compares AI visibility across multiple entities side-by-side, using specific verb and resource. Distinguishes from sibling like ai_visibility_check (single probe) and compare_entities (generic).

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

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

Explicitly frames use case for competitive AI-marketing audits with an example question. Implies when to use but does not provide explicit exclusions or alternatives beyond mentioning ai_visibility_check.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds critical behavioral details: 'Partial failures degrade gracefully — bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' It also describes the return content structure (summary block, per-advisory detail, links, alternative versions), which is not covered by annotations.

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

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

The description is front-loaded with the core purpose and efficiently packs details in a few sentences. Each sentence adds value (purpose, use cases, ecosystem limit, failure behavior). Slightly longer than minimal, but every sentence earns its place; no redundant phrases.

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

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

Given the tool has only 2 parameters, no output schema, and moderate complexity, the description fully covers: what the tool does, when to use, ecosystem scope, performance caveats, error handling, and return structure. No gaps remain for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds minor value by noting 'Scoped packages (e.g. "@types/node") are accepted.' for the 'package' parameter, but does not provide additional meaning beyond the schema for 'version' (which already states defaults). 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 starts with a specific verb ('Scan Dependency') and clearly defines the tool's composite action: it fans out across deps.dev and bundlephobia to answer the question 'should I add this npm package to my project'. It explicitly lists the aspects checked (license, advisories, version history, bundle size, etc.), making the purpose unambiguous. Among siblings, no other tool performs npm dependency scanning, so it is distinct.

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

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

The description provides explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states a clear out-of-scope condition: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', directing the agent to alternative approaches for non-npm ecosystems.

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

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

Beyond annotations (which already mark the tool as safe and idempotent), the description discloses the embedding model (BGE-base-en), windowing strategy (500-char overlapping windows), character cap (200K with truncation flag), and return format (passages with offsets and scores). This is rich behavioral context that significantly aids correct invocation.

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

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

The description is compact (about 6 lines), front-loads the core purpose and usage case, and packs technical details efficiently. 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 absence of an output schema, the description fully explains what the tool returns (passages with offsets and scores), how it works (embeddings/windowing), and its limits (200K chars). It also contextualizes usage with a sibling tool, making it complete for this simple search tool.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description does not add new semantic details beyond the schema—it merely restates the text limit and query purpose. 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 opens with 'Semantic search INSIDE a fetched record,' immediately clarifying the verb (search) and resource (inside a record). It distinguishes itself from siblings by explicitly pairing with ask_pipeworx_grounded and contrasting with tools that might perform broader searches.

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 guidance: 'Use when the record is too big to cram into the prompt — search_within saves context.' It also explains how it pairs with ask_pipeworx_grounded, providing a workflow context. This clearly tells the agent when to prefer this tool over alternatives.

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

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

Annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) indicate a non-destructive, idempotent write operation. The description adds behavioral context: persistence only for OAuth accounts, SMS limits (10/day), phone verification requirement, and always-on feed. No contradictions with annotations.

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

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

The description is relatively long but well-structured: it starts with the core purpose and return value, then requirements, then type options with examples, then delivery channels. Every sentence adds value, though some details could be consolidated. It is front-loaded and informative.

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

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

Given the moderate complexity (3 parameters, nested objects) and no output schema, the description covers necessary aspects: purpose, prerequisites, type options, delivery constraints. It lacks error handling details but provides sufficient information for correct tool selection and invocation.

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

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

Schema description coverage is 100%, meaning all parameters have descriptive schemas. The description goes beyond by providing detailed examples for each 'type' and 'params' combination, and explains field constraints for 'delivery' (e.g., SMS must match verified phone, webhook HMAC signing). This adds significant meaning.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It lists supported subscription types with examples, and distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation.

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 prerequisites ('Requires a Pipeworx OAuth account') and includes examples for each subscription type and delivery channel. While it does not explicitly state when not to use this tool, the context of sibling tools (list_subscriptions for viewing, unsubscribe for removing) implies appropriate usage. The guidance is clear but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context about the output format (category-bucketed questions with tool+argument shape) and that it draws from a live catalog. No contradictions.

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

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

The description is front-loaded with clear synonyms and purpose, but slightly lengthy. It efficiently covers what the tool does, how to use it, and when to use it. Every sentence adds value, but could be tightened.

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 value (category-bucketed examples with tool+arguments). It covers input, output, and usage context. It also explains the origin of examples (live catalog). 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% and the schema already includes detailed description for the `topic` parameter, including the list of options and the default behavior. The tool description adds no new information beyond restating the schema content, so baseline 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 tool is an onboarding entry point returning example questions. It lists synonyms like 'what can I ask Pipeworx?' and distinguishes from siblings by explicitly saying 'Use this FIRST when you do not yet know what Pipeworx can do.'

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: call with no arguments for full spread, or pass `topic` to filter. It also states when to use it ('when you do not yet know what Pipeworx can do') and mentions meta-tools like ask_pipeworx.

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 important behavioral context beyond annotations: it clarifies that the row is deactivated (not deleted) and that historical events remain available via 'recent_alerts'. 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 concise sentences pack all essential information: action, resource, ownership constraint, and effect. No wasted words; front-loaded with the core purpose.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage constraints, behavioral outcome, and relationship to sibling tools. No gaps.

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

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

Schema coverage is 100% with the 'id' parameter well-described. The description adds a semantic constraint: the id must be the user's own subscription, which is not in the schema. This adds value beyond the schema description.

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

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

The description clearly states the action 'cancel a subscription by id', specifies the resource 'subscription', and adds ownership constraint ('you can only cancel your own subscriptions') and behavioral detail ('deactivated, not deleted'). It distinguishes itself 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 explicitly states 'you can only cancel your own subscriptions', providing clear context for use. It does not explicitly mention alternatives, but the sibling tool list includes related tools, and the description effectively implies when to use it.

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

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

The description goes beyond annotations by detailing the two processing paths (SEC EDGAR/XBRL fast path for financial claims, grounded pipeline for other claims), the types of verdicts returned, and that it replaces multiple sequential calls. This adds significant behavioral context on top of the readOnlyHint and idempotentHint 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 somewhat long but well-structured. It front-loads trigger phrases, then explains functionality, then details the two paths, and finally the return value. Every sentence adds value, though it could be slightly more concise without losing clarity.

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

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

Given the complexity of the tool and the absence of an output schema, the description is quite complete. It covers purpose, input parameters, processing logic, output format (verdict, value, citation, reasoning), and usage context. It could specify the exact JSON response structure, but the current description is still comprehensive.

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?

While the input schema already provides clear descriptions for both parameters (100% coverage), the description adds extra meaning by explaining how the claim parameter works with examples and how tolerance_pct overrides the default. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides specific trigger phrases ('Is it true that…', 'fact check') and distinguishes itself from sibling tools like ask_pipeworx_grounded by focusing on factual claim verification with a verdict output.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes two processing paths for different claim types, giving implicit guidance on when to use. However, it does not explicitly state when not to use it or compare it to alternatives.

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