Crystallography

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

Annotations declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds that Anthropic calls require a BYO API key with direct billing, and explains the return structure (per-model score, confidence, signals, raw_response). 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 four sentences, front-loaded with the core function. Every sentence adds essential information: purpose, model options, output, and use cases. No fluff.

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

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

Given no output schema, the description explains the return format (per-model score, confidence, signals, raw_response + combined view). All four parameters are documented. The use cases are clear, though the exact JSON structure is not detailed—still 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%. The description adds value beyond schema by explaining the default model, the effect of _apiKey (pass-through), and the context parameter for disambiguation. It also clarifies output structure, which is not in 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: probing LLMs for AI visibility of an entity and scoring it 0-100. It specifies the verb (probe), resource (LLMs), and output (score), distinguishing it from siblings like ask_pipeworx (general Q&A) and scan_competitor_ai_presence (broader scanning).

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: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also differentiates the free default model from the paid Anthropic option, but does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by explaining the routing behavior, automatic argument filling, citation URI format, and that it works on every tier. This goes beyond the structured annotations without contradicting them.

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

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

The description is long but well-structured, front-loaded with the key directive ('PREFER OVER WEB SEARCH'), followed by purpose, examples, and alternatives. Every sentence earns its place, though it is somewhat verbose compared to more minimal descriptions.

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

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

The tool has only one required parameter, strong annotations, and no output schema, but the description still covers what the tool does, when to use it, how to use it (with examples), what it returns (structured answer with citation URIs), and how it differs from alternatives. This is complete for 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 description coverage is 100%, so the baseline is 3. The description adds examples of valid questions (e.g., 'current US unemployment rate', 'Apple's latest 10-K') which help clarify expected input, but does not provide additional parameter syntax details beyond what the schema already states. It satisfies the baseline without exceeding it.

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

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

The description clearly states that ask_pipeworx routes questions to the right one of 5,529 tools across 1,455 verified sources and returns a structured answer with citation URIs. It also positions itself as the default entry point for factual questions, distinguishing it from siblings like ask_pipeworx_grounded and deep_research.

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: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with named alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions). It also clarifies that breaking-news queries are handled by ask_pipeworx itself.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses its beta nature, the possibility of active routing candidates, the retirement of the last candidate, and that it is a full working router, not a stub. It also mentions that results are compared to decide merges, adding valuable behavioral context.

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

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

The description is compact and front-loaded: first sentence defines the tool and its relationship, second explains current status, third gives explicit usage instruction. Each sentence earns its place 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?

Despite no output schema, the description references the same response shape as ask_pipeworx, providing sufficient context. It covers the tool's purpose, current behavior, relationship to siblings, and usage, making it complete for an agent to act correctly.

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

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

The input schema fully covers all parameters with descriptions and aliases, so baseline is 3. The description adds that it shares the same arguments and response shape as ask_pipeworx, reinforcing that knowledge of the sibling tool applies here. This is a slight boost but not extensive.

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

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

The description clearly identifies the tool as a beta variant of ask_pipeworx with the same router functionality, specifying it is a universal router with 5,529 tools. It explicitly distinguishes from the stable ask_pipeworx and the grounded sibling by noting its experimental nature and identical behavior currently.

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

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

The description explicitly states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the current state (no active candidate) and how results are compared against the stable router, giving clear context for choosing between the beta and stable versions.

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. The description adds context on grounded behavior (uses only tool results), success/refusal response format with specific refusal reasons, and the extra LLM cost. 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?

Dense but every sentence carries value: purpose, mechanism, response schema, use cases, cost tradeoff. Well-front-loaded and logically organized 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 tool is complex (high-stakes reads, refusal modes, cost tradeoff) and the description fully covers return types, failure modes, and usage context. Output schema is absent but the response shape is explicitly described, making the description self-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 covers 100% of parameters, all aliases for 'question' with natural language descriptions. The description adds nothing about parameter syntax or values beyond what schema provides, so baseline 3 applies.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads' which is a specific verb-noun pair. It clearly distinguishes from sibling ask_pipeworx by emphasizing extraction using ONLY tool result content and explicit refusals, making 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?

Explicitly states when to prefer this tool ('Use whenever an answer will be quoted, cited, or acted on') and contrasts with ask_pipeworx ('prefer ask_pipeworx for casual lookups'), also noting the extra LLM call cost. This gives clear decision guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral detail: resolver contract with confidence levels, parent event extraction, news fallback handling, safety short-circuits on low confidence, wide-spread liquidity warnings, and cancellation rule parsing. 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 front-loaded with core purpose and usage. Every paragraph adds necessary detail for correct invocation: fan-out examples, response shapes, safety mechanisms, cancellation risks. No fluff – each sentence earns its place 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 must explain return values. It covers all response components (market, analysis, evidence, resolver contract, parent event, news fields) and edge cases (low confidence, closed markets, wide spreads, cancellation rules). It is comprehensive for a complex research 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 covers 100% of parameters with descriptions. The description adds valuable context: market can be slug, URL, or question text; depth values explained; include_raw use cases. Examples illustrate parameter usage. This goes beyond what the schema provides.

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

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

The description states 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' – a specific verb and resource. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly listing use cases ('should I bet on X', 'what does the data say', 'is there edge in Z').

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

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

The description gives explicit when-to-use scenarios ('Use for ...') and describes conditions that alter behavior (low-confidence match short-circuits, closed/dead markets skip fan-out, wide-spread markets carry tradeability warnings). It implicitly covers when not to use by contrasting with other tools in the sibling list.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. Description adds rich behavioral context: explains how off-calendar fiscal years are handled, data sources per type, results sorted by primary metric, and inclusion of citation URIs. No contradiction with annotations.

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

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

Description is a single dense paragraph that front-loads key use cases with example queries. It efficiently packs purpose, data sources, behavior, and efficiency gains. Could be slightly more structured with bullet points, but it's concise 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 there is no output schema, the description adequately explains returns as 'paired data + pipeworx:// citation URIs per entity' and mentions sorting. It covers data sources, limitations (max 5 entities), and efficiency benefit. For a comparison tool, this is sufficient, though more detail on the exact fields returned would be helpful.

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 both parameters with descriptions (100% coverage). Description reinforces meaning with concrete examples: for type enum it specifies data sources, for values it mentions tickers/CIKs for companies and drug names. This adds context beyond the schema's basic descriptions.

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

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

Description clearly states it performs side-by-side comparison of 2-5 companies or drugs, with specific data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs). Example queries like 'compare X and Y' and 'rank these companies' make the purpose immediately understandable. It distinguishes itself from siblings like entity_profile by noting it replaces 8-15 sequential lookups.

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

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

Explicitly advises to prefer this tool over sequential single-pack lookups when comparing entities, with examples of natural language triggers. It implies when to use but doesn't explicitly state when not to use or list alternatives. However, the context of replacing many lookups is strong guidance.

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

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

Annotations already declare readOnlyHint/openWorldHint/idempotentHint, and the description adds substantial behavioral context: decomposition into facets, parallel routing to 5,529 tools, gaps[] for unanswered parts, explicit statement that findings are never invented, contradictions[] scan, semantic excerpting behavior, timing expectations, and citation_uri fetchability guarantees. This far exceeds what annotations provide.

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

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

The description is long but every sentence serves a distinct purpose: auth prerequisites, alternative tools, internal mechanics, output format, and timing. It is front-loaded with the most critical operational constraint (account required). Minor redundancy in repeatedly mentioning ask_pipeworx for different edge cases, but overall it is efficiently structured for a tool with this 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 no output schema, the description covers all necessary context: account requirements, cost implications, return packet structure (verbatim evidence, confidence, source, fetched_at, citation), gaps[] for unanswered facets, contradictions[], hop field, and what to expect timing-wise. It also addresses failure modes (empty gaps for uncatalogued topics) and the alternative to use instead. No critical information is missing.

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

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

The input schema already covers both parameters thoroughly (100% coverage), including depth semantics. The description adds decision-relevant context beyond the schema: 'thorough' requires a paid plan, timing (15-60s, up to ~90s for thorough), and reiterates that broad questions are acceptable. This nudges above the baseline 3 for high schema coverage.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call.' It explicitly distinguishes itself from open-web search and names a sibling (ask_pipeworx) for simpler cases, leaving no ambiguity about what this tool does.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: use for broad/multi-part structured-data questions; use ask_pipeworx for single lookups, breaking news, or when not signed in. It also explains depth selection (standard vs thorough) and when each is appropriate, fully covering alternatives and exclusions.

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

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

The description adds significant behavioral context beyond annotations: it states the tool returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This provides critical details about output format and usage, consistent with annotations (readOnlyHint, idempotentHint, destructiveHint).

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

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

The description is two sentences with a bulleted list, front-loading the main purpose. Every sentence earns its place: first states function, second gives usage guidance and return details. No filler or redundancy.

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

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

Given the tool's simplicity (one required param, no output schema), the description covers the essential aspects: what it returns (names, descriptions, schemas with examples), that results are ready to use, and the 'call first' guidance. It could mention ordering or ranking criteria, but is largely complete.

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

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

Schema coverage is 100% with clear descriptions for all parameters. The description adds value by explaining that the query is natural language and provides examples like 'analyze housing market trends' and 'look up FDA drug approvals.' It also mentions the limit parameter. This goes beyond the schema's property descriptions.

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

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

The description starts with 'Find tools by describing the data or task,' clearly stating the verb and resource. It distinguishes this tool from siblings like search_within or search_structures which search within data rather than discover tools. The specific list of domains and examples reinforce its purpose.

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 when you need to browse, search, look up, or discover what tools exist for:' followed by many domains. It further advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer),' giving clear context for when to use it. While it implies when not to use (when you already know the tool), it could be more explicit about alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable behavioral context: fans out across multiple sources, mentions USPTO API sunset with soft-fail, and lists exact return fields.

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

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

Front-loaded with examples and then detailed. Slightly verbose but all information is useful; no wasted sentences.

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

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

Given no output schema, the description covers return fields, source behavior, and soft-fall. Lacks exact structure of return but is generally complete for a complex tool.

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

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

Schema coverage is 100% with descriptions. The description adds clarity about accepting ticker or zero-padded CIK and explicitly notes names are not supported, which is already stated in schema but reinforces.

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

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

The description states the tool performs a 'full cross-source profile of a US public company in ONE parallel call' with clear examples and lists specific sources and return fields. It distinguishes from siblings like 'resolve_entity'.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views and advises using 'resolve_entity' first if only a name is provided.

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

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

Annotations already provide destructiveHint=true and readOnlyHint=false. Description aligns by saying 'Delete', but adds no further behavioral context beyond annotations. 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?

Three sentences, front-loaded with the primary action. Each sentence serves a clear purpose: action, usage guidance, and cross-reference. No wasted words.

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

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

For a simple delete operation with one parameter and no output schema, the description is fully adequate. It covers purpose, usage, and relationship to siblings. 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 description 'Memory key to delete'. Description merely restates this, adding no additional detail or context beyond what the schema provides.

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

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

Description uses specific verb 'Delete' and resource 'memory by key'. It distinguishes from sibling tools 'remember' and 'recall' by explicitly mentioning them and contrasting their functions.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also pairs with 'remember' and 'recall', implying when not to use those 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, idempotent, and non-destructive behavior. The description adds transparency by detailing the process: fetches the page, extracts title/description/key links, and emits markdown. 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 four tightly written sentences with no fluff. Each sentence contributes: main action, process steps, output format, and use cases. Front-loaded and efficient.

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

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

For a tool with two parameters and no output schema, the description covers the output format (single text blob, markdown), the process, and purpose. It could mention error handling or limitations (e.g., unreachable URLs), but is otherwise complete.

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

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

Schema covers both parameters (url, max_links) with descriptions. The description reinforces their roles but does not add new semantic information beyond what the schema provides, so baseline score is appropriate.

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

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

The description clearly states the verb 'Generate', the resource 'llms.txt file for any URL', and the purpose of enabling AI crawler indexing. It distinguishes from sibling tools by specifying a unique output format and use cases.

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

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

The description provides clear use cases ('getting a client's site indexed', 'drafting llms.txt', 'auditing a competitor'), giving context for when to use the tool. It does not explicitly exclude scenarios or mention alternatives, but the use cases suffice.

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 behavior; description adds that it is 'Keyless' and details the return format (CIF text + parsed summary), providing additional context.

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

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

Concise and front-loaded with the core action and purpose, no unnecessary sentences.

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

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

Given no output schema, the description fully explains the return contents (CIF text and summary with formula, space group, cell, atom count), making it complete.

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

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

Schema covers 100% of parameters with a clear description; the tool description adds minimal new info beyond 'numeric COD ID', which is already in 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?

Clearly states it fetches a CIF file by COD ID, specifies the content (symmetry, atoms) and distinguishes from siblings by noting it provides the real atomic structure versus metadata.

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 using after search_structures/get_structure for atomic structure retrieval, providing clear context for when to invoke this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds that the tool is 'Keyless' (no authentication needed) and specifies the database source and returned fields, providing useful context beyond annotations.

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

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

Two sentences: first defines the action and how, second lists returns and keyless status. No fluff, every sentence adds value. Front-loaded with the core action.

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

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

Given the simple tool (1 param, rich annotations, no output schema), the description adequately covers what it does and returns. It could mention failure behavior (e.g., if ID not found), but the openWorldHint may imply that.

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

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

Schema coverage is 100% for the single parameter, and the description adds value by giving a real-world example ('1009000') and explaining the parameter is a numeric COD ID. This helps the agent understand the expected format 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 looks up a single crystal structure in the COD by numeric ID, listing what data it returns. It distinguishes itself from siblings like get_cif and search_structures by specifying a single structure lookup with a numeric ID.

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

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

The description implies usage for retrieving a known structure by COD ID, but does not explicitly state when not to use it or mention alternatives like get_cif for file downloads or search_structures for 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 indicate readOnlyHint, idempotentHint, destructiveHint. Description adds return field details and parameter behavior, which is useful extra context.

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

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

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

Complete for a simple list tool with one optional parameter. Lists return fields even though no output schema, and gives usage guidance.

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

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

Schema coverage is 100% and describes the parameter well. Description adds no further parameter details beyond what schema provides, so baseline 3 is appropriate.

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

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

Description clearly states 'List the caller's active subscriptions' and specifies returned fields. Distinguishes from sibling tools like subscribe/unsubscribe.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Gives clear context for when to use.

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

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

Annotations are all false, so the description carries the burden of behavioral disclosure, and it exceeds it. It reveals that filing without an account returns a claim_token, which can later be used to check resolution status. It discloses rate limiting ('Rate-limited to 5 per identifier per day') and that it is free and doesn't count against tool-call quota. It also explains the human workflow ('team reads digests daily and signal directly affects roadmap'). 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 every sentence earns its place: purpose, usage, exclusions, message guidance, claim_token, rate limit, and free/quota note. The first sentence is front-loaded with the core purpose. It loses one point because it is a dense wall of text that could benefit from paragraph breaks or bullet-style presentation, but there is no filler.

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

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

Given the tool has no output schema, the description adequately explains return values ('returns a claim_token') and later behavior ('read whether it was fixed and what changed'). It covers rate limits, account optionality, and how to frame feedback. For a feedback tool with no required parameters, the description covers all operational aspects an agent needs, including the critical exclusion for other MCP servers. It is complete without being padded.

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

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

Input schema covers 100% of parameters with descriptions, so baseline is 3. The description adds meaningful usage guidance for the 'message' parameter: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' It also clarifies the claim_token flow ('Filing without an account returns a claim_token; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed'), which supplements the schema's description with a concrete invocation example. This extra value 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 opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates concrete use cases (bug, feature/data_gap, praise), which distinguishes it from sibling research/search tools. The tool name is reinforced by the description, and the resource is clearly the Pipeworx team.

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

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

The description explicitly states when to use the tool: '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 gives an explicit exclusion: 'if the tool came from a different MCP server... we cannot fix it and reporting it here only delays you; file it with that server instead.' This is textbook when/when-not guidance, with a fallback heuristic for identification ('Not sure? Pipeworx tool names are the ones this connection lists').

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. The description adds caching behavior (5min-1h) and data source (CF analytics-engine, no PII), which are valuable 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 a single paragraph with bulleted use cases, all relevant. It is front-loaded with the core purpose and avoids 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 simple tool with one optional parameter and no output schema, the description covers what is returned (top tools, packs, call volume) and caching. No major 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%, and the description adds context about window behavior: shorter windows show current trends, longer show steady-state demand. This enriches the enum parameter 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 verb 'Returns' and the resource: top tools, top packs, and total call volume. It distinguishes itself from sibling tools by focusing on what AI agents are currently calling on Pipeworx.

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

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

Three explicit use cases are given (discovering hot data sources, confirming canonical tools, aligning use cases). It does not explicitly mention when not to use, but the guidance is clear and practical.

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, destructiveHint=false. The description adds significant behavioral context: explains the algorithmic approach (monotonicity, partition checks), semantic anchor (Jaccard threshold), partition filter (placeholder slugs), and fill check (realizable edge vs theoretical). 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?

Though lengthy, every sentence adds value. The description is front-loaded with the core purpose, then organized by mode (NO args, event, topic) with clear headers in the text. It efficiently packs algorithmic details, filters, and response structure without redundant information.

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

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

Despite no output schema, the description fully explains the response structure: opportunities array with fields (gap_pp, suggested_trade, reasoning, etc.), partition_check fields, and fill check details. It also references a sibling tool for custom sizing, making the context complete for a complex arbitrage tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds substantial meaning: explains that 'event' accepts event slugs or full URLs, recommends it for specific markets, and 'topic' triggers cross-event scanning with a search query. It also clarifies that 'topic' mode flattens markets and runs comparator on the union, going beyond schema.

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

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

The description starts with a clear verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes from siblings by mentioning alternative tool polymarket_fill_risk for custom sizing and explaining modes (trending_scan, event, topic) that are unique to this tool.

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

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

The description explicitly states when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also provides an alternative: 'For custom sizing use polymarket_fill_risk', giving clear guidance on tool selection.

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

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

The description provides extensive behavioral context beyond annotations, including caching behavior (1h at KV level), response structure with segments and diagnostics, model details, edge calculation, and tradeable-edge knobs. It does not contradict annotations (readOnlyHint, idempotentHint, destructiveHint=false).

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

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

The description is very long and detailed, which is justified for a complex tool, but it lacks conciseness. It is structured with sections but could be shortened without losing essential information. Front-loads purpose well but subsequent technical details are dense.

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

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

Given the tool's complexity (9 parameters, no output schema, no required params), the description covers all aspects thoroughly: model families, response structure, caching, diagnostics, and tradeable-edge knobs. It explains return values in detail, compensating for the lack of output schema.

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

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

All 9 parameters have schema descriptions (100% coverage), so baseline is 3. The tool description adds value by explaining the purpose and combination of knobs like min_liquidity, max_spread_pp, min_partition_leg_kelly in the context of 'TRADEABLE-EDGE KNOBS', and provides rationale for slippage_pp default.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific use case 'what should I bet on today'. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on model-driven discrepancies and providing detailed model families.

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

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

The description implies usage for discovering opportunities based on model discrepancies and mentions that Fed bets are surfaced but excluded from ranking. However, it lacks explicit guidance on when to use this tool versus alternatives like polymarket_arbitrage or polymarket_edge_tracker, which would improve clarity.

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

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

The description adds significant context beyond the annotations (readOnlyHint, idempotentHint, etc.) by explaining data gaps (cache-miss), decay calculation (daily closes, not intraday), and snapshot origin. 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 information-dense but uses mixed formats (sentence fragments, parentheticals, all-caps sections). It could be better structured with bullet points or clearer separates for response fields, but it remains functional.

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

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

Despite no output schema, the description fully details the response structure (tracked[], expired[], snapshot_dates[]) with field meanings and limitations. It covers all necessary context for an agent to interpret results correctly.

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

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

Schema coverage is 100% (both parameters documented). The description reinforces defaults and adds functional context (e.g., 'window' as 'snapshot family'). It slightly exceeds the baseline by clarifying the meaning of the parameters.

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

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

The description clearly defines the tool as providing 'Edge persistence and decay telemetry' from daily snapshots, answering a specific question about edge age and shrinkage. It distinguishes itself from siblings like 'polymarket_edges' (which likely provides current edge data) by focusing on time-series behavior.

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

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

The description implicitly guides usage by contrasting fresh vs. aged edges, and explicitly notes limitations (TTL, snapshot timing). It does not explicitly list alternatives or when to avoid, but the context is sufficient for an agent to decide.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds extensive behavioral context: it walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.), explains forced_directional_risk, and highlights the dominant loss mode. No contradictions.

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

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

The description is lengthy (~320 words) but well-structured with all-caps headings for modes and listed return fields. Every sentence adds value, though it could be slightly more terse. Given the complexity of the tool, the length is justified.

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

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

Despite having no output schema, the description comprehensively details return fields for both modes (single-market and basket), explains required conditions (one of market or event), and covers edge cases (thin legs, forced directional risk, max_clean_notional_usd). The description is fully complete for the tool's purpose.

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 rich semantics beyond the schema: explains default side auto-detection for baskets (auto from partition sum), clarifies size_usd as settlement notional for baskets with 'each share pays $1', and details the interpretation of size_usd for single-market (max spend on buys, target proceeds on sells).

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes and explicitly positions the tool relative to siblings (polymarket_arbitrage, polymarket_edges) with 'USE THIS before acting on any 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 explicit when-to-use guidance: before acting on arbitrage signals or trades above ~$500. It also warns about thin books and the risk of partial fills converting arb into directional positions, helping the agent decide when to invoke this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral context: two modes, response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and rarity of real spreads. No contradiction.

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

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

The description is detailed but well-structured with clear sections and front-loaded purpose. While it could be slightly more concise, every sentence adds value.

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

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

Given no output schema, the description explains the response structure and edge cases (compatibility_warning conditions, temporal alignment). It covers all necessary context for a comparison tool with complex matching logic.

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

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

Schema coverage is 100% and description adds examples and explains interaction between topic and explicit overrides. It provides practical guidance beyond the schema, such as that topic overrides the explicit side.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic and explicit) and mentions venue-specific participant pools, making the purpose specific and distinct from siblings 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 explicitly outlines when to use the tool (to compare spreads) and when not (compatibility_warning explains non-equivalent bet shapes or unrelated events). It warns that most pre-mapped topics are not tradeable, providing clear exclusion criteria.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds valuable behavioral context: scoping to identifier (anonymous IP, BYO key hash, or account ID) and the dual behavior (value retrieval vs. key listing). 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, front-loaded with the core action ('Retrieve a value...'), and every sentence adds value: purpose, use case, scoping, and pairing. No redundant or unnecessary text.

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

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

Given the tool's simplicity (single optional parameter, full annotations, and clear sibling context), the description is complete. It explains what the tool does, when to use it, how it behaves, and how it relates to other tools.

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% (one parameter fully described). The description adds meaning by explaining that omitting the key lists all keys, which is not explicit in the schema. It does not detail return format, but this is sufficient for the simple parameter.

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

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

The description clearly states the tool retrieves saved values or lists keys, with specific verbs ('retrieve', 'list') and resource ('value previously saved via remember', 'saved keys'). It distinguishes from sibling tools 'remember' (save) and 'forget' (delete) by its lookup 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 use: 'look up context the agent stored earlier... without re-deriving it from scratch.' It mentions pairing with remember and forget, but does not explicitly state when not to use it or provide alternatives beyond 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?

Description discloses that mark_read: true modifies state by flagging events as read, which contradicts the annotation readOnlyHint: true. This is an annotation contradiction, so score is 1 per rubric.

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

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

Description is three well-structured sentences with no wasted words. Purpose is front-loaded, filtering and mark_read are explained succinctly, and alternative access method is appended 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?

Despite no output schema, description explains return structure (source, citation_uri, raw event payload), covers all parameter behaviors, addresses polling and alternative access, and is complete for a read-heavy tool with a minor mutation side effect.

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. Description adds value by giving concrete filter examples (type 'sec_8k', ISO timestamp) and explaining the mark_read side effect, going beyond schema descriptions.

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

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

Description clearly states it pulls fired events from a subscription feed, which is specific and distinct from sibling tools like 'recent_changes' or 'list_subscriptions'. The verb 'pull' and resource 'fired events from subscription feed' are precise.

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

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

Description mentions polling works and provides an alternative URL for scripts, but does not explicitly differentiate from sibling tools or provide when-not-to-use guidance. Usage is implied but not contrasted with alternatives.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds rich behavioral detail: fans out to SEC EDGAR, GDELT→GNews fallback (with conditions), USPTO patents (with known sunset). Also describes return structure (changes[], total_changes, citation URIs). 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?

Front-loaded with examples and purpose; every sentence provides useful information. No fluff or repetition. Efficiently packs a lot of detail into a compact description.

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 return format, data sources, fallback logic, and limitations. For a 3-param tool with moderate complexity, this is fully complete and leaves no major questions.

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

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

Schema already covers all 3 parameters with descriptions (100% coverage). Description adds examples for `since` (ISO vs relative shorthand, recommended '30d'), clarifies `value` can be ticker or CIK, and gives typical monitoring recommendation. This 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?

The description starts with example queries ('What's new with X') and defines the tool as a change feed for a company in a time window. It clearly distinguishes from sibling 'entity_profile' which provides static profile, so the agent knows when to use this tool instead.

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 via example queries and directly states: 'Use entity_profile instead when you want the static profile regardless of window.' This provides both use cases and alternatives.

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

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

Beyond annotations (idempotentHint=true), description adds scoping by identifier, persistence differences for authenticated vs anonymous sessions (24h), and storage as key-value pair, which aids agent understanding.

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, each sentence adds distinct value: purpose, usage trigger, storage scope, pairing.

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-parameter tool with full schema coverage, description covers all necessary aspects: purpose, usage, storage details, and pairing. 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%, so parameters are fully described. Description reinforces key-value concept and gives examples, but adds only marginal 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 the tool saves data for reuse later, with specific examples (resolved ticker, target address, user preference) and explicitly distinguishes from sibling tools like recall and forget.

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

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

Description gives clear when-to-use guidance: 'when you discover something worth carrying forward.' It pairs with recall and forget, providing context for alternatives, though no explicit when-not-to-use.

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

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

The description adds substantial behavioral context beyond the annotations: it discloses the exact data sources (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), how identifiers are labelled by source, that unresolved identifiers are explicitly listed, and that enrichment degrades gracefully if external services are unavailable. It also notes the internal cascading lookups. This is rich, honest disclosure that aligns with readOnlyHint and idempotentHint.

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

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

The description is longer than average but well-structured: it opens with example queries and a clear purpose, then separates company and drug details, and ends with a resilience note. Every sentence carries information, though the list of example queries could be trimmed slightly. It is dense but not wasteful.

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?

Since there is no output schema, the description carries the full burden of explaining return values. It thoroughly covers company returns (CIK, ticker, company_name, LEI with ownership, FIGI, unresolved field) and drug returns (RxCUI, ingredient, brand, citation). It also explains graceful degradation and the internal multi-step nature. For a two-parameter tool, this is 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?

The schema already provides 100% parameter coverage, so the baseline is 3. The description elevates this by explaining what each type returns and giving concrete input examples for the value parameter (e.g., 'ticker (AAPL), CIK (0000320193), or name' for company; 'brand or generic name' for drug). This makes the parameters more actionable without adding syntax that the schema already includes.

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

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

The description states the tool's core function with a specific verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It enumerates concrete identifier types (CIK, ticker, LEI, FIGI, RxCUI) and explicitly positions itself as the go-to tool with 'Use FIRST whenever you have a name but need an ID,' distinguishing it from entity-related siblings.

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

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

The description gives explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and illustrates typical queries. It explains supported input formats for both types. However, it does not explicitly state when not to use the tool or name alternative tools (e.g., entity_profile for deeper dives), leaving a small gap in exclusion guidance.

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

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

The description discloses that it probes each entity using ai_visibility_check and ranks by score, explaining the mechanism beyond annotations which already indicate read-only, idempotent, and non-destructive behavior. It also explains the Anthropic API key dependency. 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?

Three sentences with no fluff: clear purpose, example usage, and output format. Front-loaded with the main action and value proposition.

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

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

No output schema, but description explains return format (ranked list with score, confidence, signal density). However, it does not reinforce the schema constraint of 2-8 entities or mention error handling for invalid inputs, leaving minor gaps.

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

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

Schema coverage is 100%, but the description adds critical context: first entity is treated as subject for narrative, context disambiguates common names, and models have defaults and dependencies explained. This adds significant 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 compares AI visibility across multiple entities side-by-side, using a specific verb (compare/probe) and resource (AI presence). It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison) by focusing on AI visibility ranking.

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

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

Provides a concrete use case (competitive AI-marketing audits) and an example question. However, it does not explicitly say when not to use or mention alternatives for single entity checks, which are available as 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?

Discloses partial failure behavior, timing (5-30s for first measurement), and graceful degradation. Annotations already indicate read-only and idempotent; description adds valuable context beyond 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?

Well-structured with clear sections (purpose, usage, return, limitations). Sentences are packed with information but not overly verbose. Could be slightly tighter by removing 'Composite' and 'in ONE call' as they are implicit.

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?

Comprehensive: covers return fields (is_latest, license, advisory_count, etc.), nested per-advisory detail, links, alternative versions, and failure behavior. No output schema, so description fully describes the 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%, so baseline 3. Description adds that scoped packages are accepted and version defaults to latest, going beyond the schema. Only minor room for improvement (e.g., expected format for version).

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 composite check for npm packages, listing specific sources (deps.dev, bundlephobia) and what it covers (license, advisories, bundle size). It distinguishes from sibling tools like scan_competitor_ai_presence.

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: 'Is X safe / popular / small' or 'what does adding lodash cost me'. Also specifies that PyPI etc. should go to deps.dev:version directly, providing clear exclusion guidance.

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

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

Annotations indicate readOnly, openWorld, idempotent, not destructive. Description adds details: formula normalization, exact stoichiometry matching, case-insensitive substring for mineral, and reporting of formula_searched. No contradictions.

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

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

Description is well-structured, front-loaded with purpose, then details. Consists of 4 sentences with no waste. Could be slightly more concise but effective.

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

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

Covers input requirements, parameter semantics, return fields, and normalization behavior. No output schema but description provides enough context. Minor gap: no mention of pagination or error handling.

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

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

Schema coverage is 100%, so baseline is 3. Description adds significant value: explains formula normalization behavior, matching rules, and that query is free-text. Mineral parameter description clarifies substring matching.

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

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

Clearly states it searches the Crystallography Open Database by compound name, formula, or mineral name, returning crystal structures with specific parameters. Distinguishes itself from siblings like get_cif and get_structure by being a search tool.

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

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

Explicitly states 'Keyless' and that at least one of query, formula, or mineral must be provided. Provides examples of inputs. Could be improved by mentioning when to prefer siblings, but 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 already declare readOnlyHint, openWorldHint, idempotentHint. Description adds valuable details: BGE-base-en embeddings, cosine over 500-char windows, 200K char cap with truncation+flag, character offsets for verification. No contradictions.

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

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

Description is a single paragraph but front-loaded with core action and key use case. Could be slightly more structured (e.g., bullet points) but no wasted words.

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

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

No output schema, so description mentions return values (top-N passages, offsets, scores) and truncation behavior. Lacks details on no-match case or pass-through of offsets, but covers most needs.

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 meaning beyond schema: explains purpose of each param, gives query examples, notes text max length. Adds value but not critical.

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 'Semantic search INSIDE a fetched record' with specific examples (SEC 10-K, article). Distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and context-saving benefit.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded. Lacks explicit when-not-to-use 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 indicate no read-only, no destruction, idempotent, and open-world. The description adds behavioral details: requires OAuth, returns new subscription ID, delivery channel options, SMS cap, webhook auto-disable after 10 failures, and HMAC signing. 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 somewhat lengthy but well-structured with clear sections for types and delivery. It front-loads the core purpose and return value. Every sentence adds value, though it could be slightly tightened without losing information.

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

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

Given the complexity of subscription types and delivery channels, the description is complete. It covers auth requirements, all 5 types with example params, three delivery options with limitations and setup details, and mentions the return value (subscription ID). No output schema exists, so the description compensates adequately.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema. It explains each type (e.g., sec_8k with ticker and items), provides usage examples for params, and details delivery channel options (email, SMS, webhook) with limitations and verification steps. The nested object for delivery is thoroughly explained.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It distinguishes itself from sibling tools like unsubscribe and list_subscriptions, and the specific subscription types are detailed.

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 context for when to use: setting up persistent subscriptions. It notes prerequisites (Pipeworx OAuth account), and limits (10/day SMS cap). While it doesn't explicitly list alternatives, it implies that anonymous/BYO accounts cannot persist subscriptions, guiding appropriate usage.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's safe. The description adds value by explaining that it returns category-bucketed example questions with tool+argument shapes, and that it is non-destructive. 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 the purpose and usage, followed by examples. It is slightly verbose with the exhaustive category list, but each sentence adds value. Still concise enough for its purpose.

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

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

Given low complexity (1 optional param, no output schema), the description fully covers what the tool returns, when to use it, and how to call it. It provides ample context 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% (1 param 'topic' with description). The description echoes that 'topic' is optional and lists focus areas, but adds only marginal context beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it returns category-bucketed example questions to help users learn what to ask, with a specific verb ('returns') and resource ('example questions'). It distinguishes from sibling tools like 'ask_pipeworx' by positioning itself as the onboarding entry point.

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

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

The description explicitly says to 'use this FIRST when you do not yet know what Pipeworx can do', providing clear context for when to use. It also explains optional topic filtering. However, it does not explicitly state when not to use it or contrast with sibling tools, missing some 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?

Description adds value beyond annotations: it explains deactivation (not deletion) and that historical events stay available. Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true; description matches and enriches with why it's not destructive and what happens to history.

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 concise sentences, no fluff. Action is front-loaded ('Cancel a subscription by id'). Every sentence earns its place (ownership enforcement, deactivation detail, historical data note).

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 single-parameter tool with no output schema, the description covers purpose, ownership constraint, and effect on data (deactivation + history). No missing context for correct usage.

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

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

Only one parameter ('id') with schema description 'Subscription id (uuid) returned by subscribe.' Schema coverage is 100%, so the description adds little beyond restating 'by id'. 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 states 'Cancel a subscription by id' with specific verb ('Cancel') and resource ('subscription'), and clarifies it deactivates rather than deletes, distinguishing it from a delete operation. Sibling tools include 'subscribe' and 'list_subscriptions', so purpose is clear.

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

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

The description explicitly says 'Ownership is enforced — you can only cancel your own subscriptions', which tells when to use (own subscriptions) but does not mention when not to use or alternative tools like 'list_subscriptions' to find subscriptions. Still clear enough for most agents.

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

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

Beyond the readOnly/idempotent annotations, the description discloses verdict values, the critical semantics of could_not_verify (not evidence for/against), the meaning of unsupported, and the internal routing. It also warns callers about verification_error, adding substantial context that the annotations alone do not convey.

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

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

The description is dense but well organized: trigger phrases, use context, routing logic, return types, and an IMPORTANT caller warning. It is longer than average but every sentence contributes useful information; only slight verbosity prevents a 5.

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

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

Even without an output schema, the description fully specifies return values (verdict, actual value, citation, reasoning) and distinguishes important edge cases (could_not_verify vs unsupported). This makes the tool's behavior predictable and complete 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 description coverage is 100%, and both parameters are already well-documented in the schema. The tool description adds no parameter-specific meaning beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description clearly identifies the tool's function: natural-language claim verification against authoritative sources, with a specific verb ('verify'), a resource ('authoritative sources'), and concrete trigger phrases. It also distinguishes itself from siblings by noting it replaces 4–6 sequential calls and handles both structured company-financial claims and a grounded fallback for other claims.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and provides clear routing guidance: company-financial claims take the SEC EDGAR + XBRL path, any other factual claim falls through to the grounded pipeline. However, it does not explicitly mention when NOT to use this tool or compare it to alternatives like ask_pipeworx_grounded, so it loses a point.

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