Figma

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds clarity on default model (Workers AI Llama-3.3-70b, free), the BYO key requirement for Anthropic, and the return format (per-model + combined view). No contradictions with annotations. It doesn't discuss rate limits or potential costs, but the transparency is adequate.

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

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

The description is two sentences with no filler. The first sentence states the core purpose and outcome, the second adds key details (default model, BYO key, return format, usage scenarios). Every sentence earns its place.

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

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

Despite having no output schema, the description explicitly states the return structure (per-model fields + combined view). It covers all four parameters and their semantics. Given the tool's moderate complexity and the richness of annotations, the description is fully sufficient for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds meaningful context beyond the schema: defines 'entity' as brand/business/product/person/topic, clarifies model options and the _apiKey requirement, and explains the optional 'context' parameter for disambiguation. This adds value without redundancy.

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 knowledge about an entity and scoring visibility on a 0-100 scale. It uses specific verbs ('probe', 'score'), identifies the resource ('LLMs'), and distinguishes from sibling tools focused on general Q&A (ask_pipeworx) or research (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 explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly state when not to use the tool, but the listed scenarios provide clear context. The absence of alternative recommendations keeps it from a perfect score.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, so safety is covered. The description adds valuable behavioral context: it routes to 5,430 tools, fills arguments automatically, and returns structured answers with pipeworx:// citation URIs. It also notes it is the default entry point and works on every tier, which goes beyond the annotations and helps the agent understand the tool's operation.

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

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

The description is long but well-structured and front-loaded with the core guidance in the first sentence. It packs in trigger phrases, examples, and alternative tool guidance without redundancy. Some promotional phrasing ('PREFER OVER WEB SEARCH', 'START HERE') could be trimmed, but overall it is information-dense and organized effectively for an agent.

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

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

Despite lacking an output schema, the description covers return expectations by mentioning 'structured answer with stable pipeworx:// citation URIs'. It also comprehensively addresses scope (SEC filings, FDA, FRED, etc.), usage context (default entry point, one fast call), and relationships to sibling tools, making it highly complete for the tool's complexity.

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

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

The schema covers all six parameters with descriptions at 100%, including aliases for the question parameter, so the baseline is 3. The description adds value by giving concrete example questions ('current US unemployment rate', 'Apple's latest 10-K', etc.) that illustrate the expected format and breadth of queries, effectively serving as parameter-level examples beyond the schema's generic description.

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

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

The description clearly states the tool answers factual questions by routing to thousands of verified sources and returning structured answers with citations. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives, making its specific role unambiguous.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', a list of trigger phrases ('what is', 'look up', etc.), and concrete example queries. It also gives clear conditions for stepping up to alternatives (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions), making the choice between tools precise.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable context: experimental nature, candidate routing may be active, results are compared against the stable router to decide merges, and it currently matches ask_pipeworx exactly. It also clarifies it has no fallback (full working router). No contradiction with annotations observed.

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 and front-loaded with the core purpose. It includes some verbose details (e.g., 'the last was retired on outcome evidence 2026-07-26', 'Falls back to nothing — this IS a full working router') that could be tightened, but overall every sentence provides useful context without being excessively long.

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

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

For a universal router with no output schema, the description covers the beta status, identical behavior to ask_pipeworx, candidate activation logic, and current state. It references 'same response shape' as ask_pipeworx, which is adequate given the sibling tool exists, but it does not independently describe the return format.

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%: all six parameters (q, text, input, query, prompt, question) are documented as aliases for the question. The description adds no parameter-specific meaning beyond that, so the baseline of 3 is appropriate.

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

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

The description clearly states it is a beta version of ask_pipeworx, an identical universal router with 5,430 tools, same arguments, and same response shape. It distinguishes from the stable sibling by noting candidate routing improvements are enabled live under test, and explicitly says it is a full working router (not a fallback).

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

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

The description gives explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also provides current-state context (no active candidate, so currently matches ask_pipeworx exactly) which helps decide when to use it. However, it does not explicitly state when NOT to use it or compare to other siblings like ask_pipeworx_grounded.

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

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

Goes beyond annotations by detailing the exact success return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and all refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). Also discloses the extra LLM call cost. Consistent 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?

Dense but well-organized: starts with the core purpose, then the process, return contract, refusal behavior, usage guidance, and cost comparison. Every sentence delivers essential information with no filler.

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

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

No output schema exists, but the description compensates fully by specifying the exact JSON response for both success and refusal cases. It also covers routing, source count, and cost, making the tool fully self-contained 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?

The schema has 100% coverage for all six parameters, explaining that q, text, input, query, prompt are aliases for 'question'. The description adds no additional parameter-level meaning beyond what the schema states, so the baseline of 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 clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' and specifies the exact behavior: it extracts answers only from the tool result. It differentiates from the sibling ask_pipeworx by highlighting the refusal behavior and one extra LLM call cost.

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 provides usage context: 'Use whenever an answer will be quoted, cited, or acted on...' and contrasts with ask_pipeworx: 'prefer ask_pipeworx for casual lookups.' This gives the agent clear decision criteria.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds considerable behavioral context far beyond annotations: it details fan-out logic per classifier, resolution confidence handling, parent event extraction, news fallback mechanisms, safety short-circuits for low-confidence and closed markets, illiquidity warnings, and resolution-rule risk. Contradictions with annotations are absent.

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

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

The description is lengthy but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and is front-loaded with the core purpose. While every sentence adds value, some details (like specific FRED series) could be deferred to a documentation page, making it slightly verbose for a tool 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 the tool's complexity (multiple classifiers, fan-out to diverse sources, resolution confidence, parent events, news fallbacks, resolution rules) and the lack of an output schema, the description provides exhaustive context. It covers all major behavioral aspects, edge cases, and response fields, ensuring an agent can use the tool correctly without guesswork.

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

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

Schema coverage is 100% with descriptions for all three parameters. The tool description enriches parameter understanding by clarifying input format variations for 'market', explaining the trade-off for 'depth', and the effect of 'include_raw' on response size. Examples in the schema also aid interpretation.

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 statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies accepted input formats (slug, URL, question text) and delivers a distinct output (evidence packet + comparison). This is further differentiated from sibling tools by providing specific use cases and classifier categories.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also covers many conditional paths (low-confidence matches, closed markets, wide spreads, resolution rules) that inform appropriate use. However, it does not explicitly mention when not to use or provide direct alternatives among sibling tools.

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

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

Annotations (readOnlyHint, openWorldHint, idempotent) indicate safe, non-destructive behavior. The description adds significant behavioral context: specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and that it replaces 8–15 sequential lookups. 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 reasonably concise given the detail needed. It front-loads common use cases and then explains data sourcing. A few minor redundancies (e.g., repeating 'largest/most/biggest' after sorting mention) but overall well-structured.

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

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

Despite no output schema, the description fully explains what data is returned for each entity type (financials for companies, adverse events/approvals/trials for drugs), sorting behavior, and citation URIs. The tool is well-defined for an AI agent to understand inputs and outputs.

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 both parameters. The description provides additional context (e.g., tickers/CIKs for company, names for drug, max 5 items), but this largely mirrors schema semantics. Baseline 3 is appropriate as the description adds marginal 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 specifies the tool's purpose: side-by-side comparison of 2–5 entities (companies or drugs). It lists common use cases ('compare X and Y', 'which is bigger', 'rank these companies') and explicitly distinguishes from sequential single-entity lookups, making it clear when this tool should be preferred over siblings like 'entity_profile'.

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

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

The description provides clear usage guidance: use for comparisons, head-to-head, ranking. It explicitly states 'ALWAYS PREFER over sequential single-pack lookups'. While it doesn't explicitly list when not to use (e.g., for single entities), the context implies that entity_profile is for single lookups. The guidance is adequate but 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?

The description goes far beyond the readOnly/idempotent annotations, detailing return format (verbatim evidence, confidence, source, fetched_at, citation, gaps[]), latency expectations, parallel routing, semantic excerpting behavior, and the contradictions[] array. It also discloses the paid-plan constraint for 'thorough', which is not visible in annotations or schema.

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

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

The description is long but every sentence adds distinct value—account constraints, core function, use cases, alternatives, depth semantics, return structure, and latency. It is front-loaded with the critical 'ACCOUNT REQUIRED' notice and organized logically, though it could be tightened by merging some depth explanations.

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?

There is no output schema, so the description carries the burden of explaining return values, which it does thoroughly: findings packet, gaps[], contradictions[], hop, citation_uri. It also covers account prerequisites, latency, and the tool's relationship to siblings, making it complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining how 'depth' affects number of facets and recovery hops (standard adds gap recovery+contradictions, thorough adds iterative pass) and reinforces that 'question' can be broad/multi-part. This is more than what the schema alone provides, but not a huge increment.

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

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

The description explicitly states the tool performs 'grounded multi-source research across Pipeworx's 1408 STRUCTURED data sources' in one call, and contrasts it with open-web search and alternative tools like ask_pipeworx. It names the verb ('research'), the resource (structured data sources), and differentiates it from siblings by scope and output.

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

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

It gives clear when-to-use guidance: 'best for broad/multi-part questions over structured data', with explicit alternatives for single lookups (ask_pipeworx) and breaking/current news (ask_pipeworx). It also explains account requirements and when to use which depth level, making tool selection decision very concrete.

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 by explaining return format (top-N tools with full input schemas, curated examples, ready to call directly). Annotations already declare readOnly and idempotent, but description enriches behavioral 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?

Single paragraph, front-loaded with core purpose, covers key points without excessive verbosity. Could be slightly more structured but is 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?

Completeness is high given no output schema: description explains return value in detail including that each result is ready to call directly. Covers all relevant aspects for agent invocation.

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

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

Parameters are 100% described in schema, including aliases. Description mentions aliases but adds no new semantic meaning beyond schema. Baseline 3 is appropriate.

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

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

Description clearly states purpose: find tools by describing task. Lists specific domains (SEC filings, FDA, etc.) and distinguishes from siblings which are specific tools.

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

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

Explicitly says 'Use when you need to browse... discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear when-to-use guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: parallel fan-out across multiple sources, soft-fail for patents, and specific return fields. 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 fairly long but every sentence is informative. It is front-loaded with example queries. Could benefit from bullet points for return fields, but overall efficient and clear.

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

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

Despite no output schema, the description thoroughly explains all returned components (cik, filings with URIs, fundamentals sorted, patents soft-fail, news fallback, LEI). It covers error handling and prerequisites, making it complete for a 2-param tool.

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

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

Schema coverage is 100%, so baseline 3. The description adds nuance: names not supported (use resolve_entity), value can be ticker or zero-padded CIK, and type is currently only 'company'. This extra context justifies a 4.

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

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

The description clearly states it returns a full cross-source profile of a US public company, lists example queries like 'Tell me about X' and 'company profile for Microsoft', and details the output fields (cik, filings, fundamentals, patents, news, LEI). It distinguishes itself 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 when the user asks for a holistic view.' It also delegates to resolve_entity when only a name is given, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about sensitive data clearing and pairing with other tools, but does not cover edge cases like deleting a nonexistent key. 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 two sentences long, front-loaded with the action, and contains no unnecessary words. Every sentence adds value.

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

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

For a simple destructive tool with clear annotations and a single parameter, the description is fully complete: it states purpose, usage scenarios, and relationships to sibling tools. No output schema needed.

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

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

Schema coverage is 100% with the key parameter described as 'Memory key to delete'. The description does not add additional semantics beyond what the schema provides, resulting in a baseline score of 3.

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

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

The description explicitly states 'Delete a previously stored memory by key', clearly specifying the verb (delete), resource (memory), and method (by key). It distinguishes the tool from siblings like remember and recall.

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

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

The description provides clear when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also explicitly pairs with related tools remember and recall.

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. Description adds that it fetches and extracts title/description/links, aligning with annotations and providing useful context about the extraction process.

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 covers purpose and output, second lists use cases. No fluff, front-loaded with core information, and every word serves a purpose.

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

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

Given only 2 parameters, no output schema, and no nested objects, the description sufficiently covers input, process, and output. It also includes practical usage scenarios, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds examples (e.g., specific landing page) and mentions default (25) and max (50) for max_links, enhancing understanding beyond the schema.

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

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

Description clearly states the tool generates a 'production-ready llms.txt file' for AI crawlers, specifying the process (fetches, extracts, emits) and output format. It distinguishes itself from siblings like deep_research or entity_profile by focusing on a specific web-standard file generation for AI indexing.

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

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

Explicitly lists three use cases: getting a client's site indexed, drafting llms.txt, or auditing competitor views. Does not explicitly state when not to use or provide alternatives, but the context is clear and covers common scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds context about the compact nature and returned fields but does not provide additional behavioral insights beyond what annotations convey. Since annotations are strong, the description's contribution is moderate.

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

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

The description is concise, consisting of two sentences. The first enumerates returned fields efficiently, and the second provides a clear use case. No redundant or extra information is present.

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

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

For a simple read-only tool with only two parameters and no output schema, the description fully explains what the tool returns (list of fields) and its intended use (understanding file structure). No additional information is necessary.

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 both parameters are well-described in the schema. The description mentions the file key and implicitly relates to depth by mentioning 'compact summary' and 'without fetching full node tree', but it does not explicitly clarify how the depth parameter affects the output or when to adjust 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 identifies the tool's action (get a compact summary), specifies the resource (Figma design file by file key), and lists the exact fields returned (name, last modified, etc.). It also distinguishes from sibling tools like get_file_nodes by noting it avoids fetching the full node tree.

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

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

The description states when to use this tool ('to understand the structure... without fetching the full node tree'), implying it is appropriate for high-level overviews. However, it does not explicitly mention when not to use it or provide direct alternatives beyond the implicit contrast with full node tree retrieval.

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, and destructiveHint. The description adds the return format (map of node ids to URLs) but does not elaborate beyond that. No contradiction with annotations.

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

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

Two sentences with no extraneous information. The first sentence defines the core action, the second clarifies usage and output formats. 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 4-parameter tool with no output schema, the description explains the return type and format options. However, it could be more explicit about the map structure and the comma-separated format for node IDs (though captured in schema). Adequate for the complexity.

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

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

Schema description coverage is 100%, so the schema already fully documents parameters. The description adds a brief mention of output formats (PNG, SVG, JPG) but does not provide meaningful additional semantics beyond what the schema offers.

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 renders images of specific Figma nodes and returns a map of node IDs to image URLs. It uses a specific verb ('Render') and resource ('images of specific nodes'), and the mention of 'visual previews' distinguishes it from sibling tools like get_file_nodes that retrieve node data.

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

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

The description says 'Use to get visual previews...', implying when to use, but does not explicitly exclude alternatives or name sibling tools. However, the context of the design file and the distinction from data retrieval tools is clear enough.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the return format detail but no additional behavioral traits beyond annotations. The description adds some value but is not heavily burdened due to rich annotations.

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

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

Two sentences: first states action, second specifies return format and typical usage. Every word earns its place; no wasted content. Highly concise and well-structured.

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

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

Given the tool's simplicity, good annotations, and full schema coverage, the description covers purpose, return format, and usage. No output schema exists, but the description outlines the return structure. Complete enough for effective use.

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

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

Schema coverage is 100% with parameter descriptions. The description adds no new semantic meaning beyond what's in schema; it simply reiterates 'by their node ids'. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves specific nodes from a Figma design file by ID, and specifies the return format (compact map of id to name/type). It distinguishes from siblings like get_file (whole file) or get_file_images.

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 advises using the tool to 'inspect particular frames, components, or layers,' implying use cases. It does not explicitly exclude alternatives or contrast with siblings, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description's job is lighter. The description adds value by listing the actual fields returned (id, email, handle, avatar). No behavioral details beyond the annotations are needed, and there is no contradiction.

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

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

Two efficient sentences: the first states the action and result, the second gives usage context. No unnecessary words; front-loaded with key information.

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

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

Despite no output schema, the description lists the returned fields (id, email, handle, avatar). The tool is simple and has no parameters, so this covers what an agent needs to know. Complete for the given complexity.

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

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

With 0 parameters, the baseline is 4. The input schema has no properties, so the description correctly adds no further parameter info. This is appropriate for a parameterless tool.

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

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

The description clearly states the action 'Get the signed-in Figma user' and lists the specific fields returned (id, email, handle, avatar image URL). It also provides a use case: 'identify whose Figma account is connected.' This distinguishes it from siblings which are unrelated to user identity.

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 includes a clear usage context: 'Use to identify whose Figma account is connected.' It implicitly tells when to use this tool (when you need current user info) but does not explicitly state when not to use it or mention alternatives. Since it's a simple read with no parameters, the guidance is adequate.

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 mark the tool as read-only, idempotent, non-destructive. Description adds value by listing returned fields (id, message, author handle, created time, resolved time). No contradictions with annotations.

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

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

Two concise sentences with no wasted words. Each sentence serves a purpose: defining the action and stating return fields and usage.

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

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

For a simple, well-annotated tool with one parameter, the description is complete. It specifies the resource, action, return fields, and usage context. No output schema needed given the explicit listing.

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

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

Input schema has 100% coverage with a clear description for file_key. The tool description does not add additional parameter information beyond what the schema provides, so baseline score 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?

Clearly states verb 'List' and resource 'comments on a Figma design file'. Distinguishes from sibling tools like get_file and get_file_nodes by targeting comments specifically.

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 clear usage context: 'Use to review feedback and discussion on a design.' No explicit alternatives or when-not-to-use, but the sibling set lacks direct comment-focused 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 convey readOnly, idempotent, and non-destructive behavior. The description adds value by listing the returned fields and the scope (caller's subscriptions), which goes beyond the annotations.

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

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

The description is two sentences, front-loaded with the purpose, and every part contributes meaning. No excessive wording.

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

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

Given the simple tool with one optional boolean parameter, rich annotations, and no output schema, the description fully covers the tool's functionality, use case, and return values.

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

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

Schema coverage is 100% with a clear description of the single parameter. The description does not add any additional meaning beyond the schema, so 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 explicitly states 'List the caller's active subscriptions' with a specific verb and resource, and it distinguishes itself from siblings like subscribe and unsubscribe by clarifying its role.

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

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

The description provides clear guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel,' which tells when to use the tool and relates to sibling tools.

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

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

Annotations are all false, so the description carries the burden of explaining side effects. It adds meaningful behavioral context: rate-limited to 5 per identifier per day, free, does not count against quota, team reads digests daily, and feedback affects roadmap. It also provides privacy guidance (don't paste the end-user's prompt), which is beyond what annotations reveal.

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

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

The description is thorough but not bloated. Every sentence provides actionable guidance: purpose, usage, exclusions, content tips, rate limit, and impact. It is well-structured, front-loaded with the core verb, and uses compact phrasing without redundancy.

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

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

For a feedback tool with no output schema, the description fully covers what the tool does, when to use it, how to format the feedback, what not to include, and the operational constraints (rate limit, quota). It leaves no significant gaps for an agent to guess about.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by advising how to phrase feedback ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and emphasizing specificity in the message field. This goes beyond the schema's brief descriptions, though it doesn't explain every parameter in depth.

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 with a specific verb ('Tell'), a resource ('the Pipeworx team'), and the exact scope (reporting broken, missing, or needed capabilities). It also distinguishes itself from sibling tools by explicitly scoping feedback to tools served by this Pipeworx connection and directing other-server issues elsewhere.

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 for each feedback type (bug, feature, data_gap, praise) and an explicit when-not-to-use exclusion (different MCP server). It also mentions the daily rate limit and that it doesn't count against the tool-call quota, which helps an agent decide if this is the right path.

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

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

Annotations already indicate read-only, idempotent, open-world. Description adds that data is derived from CF analytics-engine, no PII, cached 5min-1h. No contradictions, and the added behavioral details are valuable.

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, then use cases, then data details. No fluff, 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?

Despite no output schema, description clarifies return structure (top tools, packs, volume), caching, and data source. For a simple 1-param optional tool, this is fully complete.

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

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

Schema coverage is 100% with enum values described. Description adds context on window trade-offs (shorter for hot, longer for steady-state). Adds meaning beyond the schema's basic enum description.

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

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

Clearly states that the tool returns top tools, top packs, and total call volume on Pipeworx, with a specific verb-resource combo. Distinguishes from siblings like ask_pipeworx or discover_tools by focusing on trending usage data.

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 three explicit use cases (discovering hot sources, confirming canonical tool, aligning use case with demand). Lacks explicit when-not-to-use or alternatives, but the use cases are specific enough for good 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 read-only, idempotent, non-destructive. Description adds rich behavioral context: response includes opportunities array, partition check details, fill check logic, Jaccard similarity filter, and placeholder filter. No contradictions.

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

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

Thorough and well-structured, but slightly long. Front-loads core purpose and breaks down modes clearly. Every sentence adds value, but could be tightened slightly.

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

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

Given the tool's complexity (3 modes, multiple sub-checks, no output schema), the description is fully complete. Covers semantic anchor, partition filter, fill check, and references related 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% with good descriptions. The description adds nuance: event accepts slug or full URL, topic is a seed question, and explains each mode's behavior in detail, significantly enhancing understanding.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (no args, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: no args for trending scan, event for specific market (recommended), topic for cross-event scanning. Also warns when not to trade (realizable_edge_pp ≤ 0) and references polymarket_fill_risk for custom sizing.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds significant behavioral context: caching at KV level, model families, edge calculation details, slippage assumptions, diagnostic feedback. 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 front-loads the core purpose, but it is overly verbose with detailed model family explanations and response structure. Could be trimmed by ~30% without losing essential guidance for an AI agent.

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

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

Despite no output schema, the description thoroughly explains the return structure (by_segment, fed_candidates, diagnostics), all parameters are documented, and caching behavior is disclosed. It covers everything needed for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial meaning beyond schema for parameters like min_partition_leg_kelly, slippage_pp, and category_filter, explaining their interplay and use cases. Only a few parameters (e.g., limit) are not further enriched.

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 from siblings like polymarket_arbitrage by focusing on edge signals, not just 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 implies usage for discovering betting opportunities but does not explicitly state when not to use this tool versus alternatives like polymarket_edge_tracker or polymarket_arbitrage. Usage is implied but lacks exclusions or comparative 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 declare readonly, idempotent, non-destructive. The description adds useful behavioral context: history bounded by 60-day TTL, decay from daily closes (not intraday), snapshot gaps when no scan occurred. This goes 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 relatively long but well-structured: purpose first, then output fields, then limitations. Every sentence adds value. It could be slightly more concise, but overall it is earned.

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 details the response structure (tracked, expired, snapshot_dates) and edge computation nuances. It also covers input, output, limitations, and data sources, making it fully informative.

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

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

Schema coverage is 100%, so baseline is 3. The description restates parameter defaults and meaning but does not add new meaning beyond the schema descriptions. It is adequate but not exceptional.

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

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

The description clearly states the tool provides 'Edge persistence and decay telemetry' and answers a specific question about edge duration and trend. It uses specific verbs ('track', 'answers') and resource ('edge persistence/decay'). It distinguishes from sibling tool 'polymarket_edges' by focusing on time-series analysis.

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

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

The description implies when to use by contrasting fresh vs old edges, but it does not explicitly state when not to use or mention alternative tools among siblings. Usage guidance is present but lacks exclusions or direct comparison.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive; the description adds rich behavioral details like ladder-walking logic, specific result fields (e.g., max_fillable_usd, thin_legs), and risk factors (forced_directional_risk). No contradiction with annotations.

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

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

The description is long but well-structured: it front-loads the overall purpose, then logically separates single-market and basket modes with clear formatting. Each sentence adds value, though some redundancy could be trimmed. It's not unnecessarily verbose given the 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 two modes, no output schema, and no nested objects, the description is exceptionally complete: it explains the calculation logic, expected outputs, risk factors, and when to use it. The agent can fully understand the tool's behavior and invocation context.

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

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

Although schema description coverage is 100%, the description adds meaning beyond the schema: it explains that size_usd for basket is 'settlement notional — shares per leg, each paying $1 at resolution,' clarifies side auto-detection for baskets, and notes clamps (10–1,000,000). This enriches the bare schema definitions.

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 a 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' specifying two distinct modes (single-market and basket) and listing exact outputs like top_of_book, vwap_fill_price, and verdict. It differentiates from sibling tools by directly stating to use this before acting on polymarket_arbitrage or polymarket_edges signals.

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 the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also provides context on why theoretical overround may be uncapturable and warns about partial basket fills converting arb into directional risk.

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

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

Annotations indicate readOnly, idempotent, and non-destructive. The description adds extensive behavioral context: response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and edge cases (non-equivalent bet shapes, temporal mismatch). This goes well 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 well-structured with clear sections (overview, modes, response, safety fields) and front-loaded with purpose. However, it is somewhat verbose and includes repetitive explanations (e.g., compatibility warning described twice). Could be slightly tighter.

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 and no nested objects, the description thoroughly explains the response format, safety fields, and edge cases. It provides sufficient context for an agent to understand invocation, including behavior when conditions are not met. Complete for a tool of this complexity.

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

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

All 3 parameters are described in the schema (100% coverage). The description adds significant meaning: explanation of the two modes (topic vs explicit), the list of 10 topic shortcuts, and field override semantics. This adds more value than the baseline of 3.

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

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

The description clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools by focusing on cross-venue comparison, with explicit modes (topic shortcuts vs explicit tickers) and detailed 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?

It explains when to use (cross-venue spread analysis) and provides strong contextual guidance about limitations (most pre-mapped topics return compatibility warnings). It also describes safety fields that indicate when spreads are not meaningful. However, it does not explicitly name alternative tools for single-venue analysis.

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. The description adds useful behavioral context: 'Scoped to your identifier' and explains behavior when key is omitted. No contradictions.

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

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

Three concise sentences with no redundancy or wasted words. Front-loaded with the core action, then usage context, then scoping, then pairing. Every sentence earns its place.

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

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

No output schema exists, but the description mentions 'retrieve a value' and 'list all saved keys', which covers the basic return behavior. It also ties into the sibling tools. Could be improved by describing the output format (e.g., the value or an array of keys).

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 meaning by explaining the effect of omitting the key (list all keys) and the purpose of the key (memory key to retrieve). It goes beyond the schema's basic description.

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

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

The description clearly states the verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys'. It distinguishes from siblings 'remember' and 'forget' by naming them, making the tool's role in the triad explicit.

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

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

Provides explicit context for use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch'. Mentions scoping and pairing with remember/forget, but does not explicitly state when not to use it or alternatives among other siblings.

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

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

Annotations indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: returned fields, mark_read flagging behavior, and external access via URL. No contradictions.

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

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

Four sentences, front-loaded with purpose, followed by return fields, filtering/state change, and external access. Every sentence adds value; no unnecessary words.

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

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

Given no output schema, the description explains return fields, filtering, and mark_read behavior. It covers core usage and mentions external access. However, it does not address pagination beyond limit (e.g., if a cursor is needed), but given the open world hint, this is acceptable.

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 descriptions cover all 5 parameters. The description adds examples (type 'sec_8k'), clarifies the effect of mark_read, and mentions default limit (50) and range (1-200). This provides practical guidance 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 pulls fired events from a subscription feed, returning recent alerts with source, citation_uri, and raw payload. It distinguishes from sibling tools like list_subscriptions and subscribe by focusing on retrieving specific alert events.

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 how to filter by type and since timestamp, and how mark_read affects subsequent calls. It also mentions polling is fine and an alternative URL. However, it does not explicitly state when not to use or compare to other 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 fan-out to multiple sources, fallback behavior (GDELT→GNews), soft-fail for USPTO, accepted date formats (ISO or relative), return format (structured changes with URIs). No contradiction with annotations (readOnlyHint, etc.).

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 and front-loaded with query examples. Slightly verbose but every sentence adds value; could be trimmed without losing key info.

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 format (changes grouped by source, total_changes, URIs). Covers failure modes (rate-limiting, sunset API) and date handling, making it complete for a multi-source change feed 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 100% (baseline 3). Description adds practical usage examples for 'since' (e.g., '30d', '1m') and clarifies 'value' accepts ticker or CIK, enhancing 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 tool as a change feed for companies, enumerates data sources (SEC, GDELT/GNews, USPTO), and provides query examples. Explicitly distinguishes from sibling tool entity_profile.

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

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

Provides explicit when-to-use examples (e.g., 'What's new with X', 'latest on Y') and when-to-use-alternative directive for entity_profile. Also notes limitations like USPTO soft-fail and GDELT→GNews fallback.

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

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

The description adds important behavioral context beyond annotations: scoping by identifier, 24-hour retention for anonymous sessions, and persistent memory for authenticated users. Annotations already indicate idempotent and non-destructive, and description aligns. Minor gap: no mention of overwriting behavior on duplicate keys, but overall strong.

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 concise sentences, each meaningful. The core purpose is front-loaded, and every sentence adds value—usage guidance, examples, scope, retention, and pairing. No waste.

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

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

For a simple 2-param tool with no output schema, the description is quite complete. It covers purpose, when to use, pairing, scoping, and retention. It does not mention error cases or return value, but those are minor given the simplicity.

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

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

Schema coverage is 100% with clear param descriptions. The description reinforces key-value pair concept and gives typical key examples, adding value beyond the schema.

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

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

The description clearly states the tool saves data for reuse, with specific examples like 'resolved ticker' and 'user preference'. It distinguishes itself from sibling tools by referencing '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?

The description explicitly guides when to use the tool ('when you discover something worth carrying forward'), provides concrete examples, and mentions pairing with related tools (recall, forget). It also clarifies persistence behavior for different authentication states.

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

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

Annotations already declare safe, idempotent behavior. Description adds that calls cascade through multiple endpoints internally and replaces manual lookups, enhancing transparency beyond annotations. No contradictions.

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

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

Description is a single, well-organized paragraph that front-loads with common queries and clearly separates supported types. It is concise yet comprehensive, though could be slightly more structured for readability.

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 adequately explains return values for both types, including format (ticker, CIK, RxCUI) and citation URIs. Missing error handling or limits, but sufficient for a lookup 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%, providing baseline 3. Description adds value by explaining acceptable inputs for each type (e.g., company accepts ticker, CIK, or name) and details on return results, enriching parameter understanding.

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

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

Description uses specific verbs (resolve, look up) and examples ('What's the ticker for...') to clearly convey the tool's purpose of converting names to canonical IDs. It distinguishes itself from sibling tools like entity_profile by specifying it's for obtaining IDs first.

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

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

Explicitly states 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. Does not explicitly list when not to use or name alternatives, but the context implies its role.

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

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

Annotations already declare readOnly, idempotent, openWorld. The description adds process details: it probes each entity with ai_visibility_check, ranks, and surfaces results. No contradictions; provides useful behavioral context beyond annotations.

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

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

Three sentences with no wasted words. Front-loaded with the main action, followed by examples and return details. Every sentence earns its place.

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

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

Despite no output schema, the description summarizes the return structure (ranked list with score, confidence, signal density). It covers purpose, usage, parameters, and output. Lacks mention of potential size limits or error handling, but adequate for this tool's complexity.

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

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

Schema covers 100% of parameters with descriptions. The description adds value by explaining that the first entity in the array is treated as the 'subject' for narrative, which is not in the schema. This extra semantic enhances understanding.

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

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

The description uses specific verbs: 'Compare', 'Probes', 'ranks', 'surfaces', and identifies the resource as 'AI visibility across multiple entities'. It distinguishes from sibling tools by specifying the use of ai_visibility_check and the ranking/competitive comparison aspect.

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 a use case ('competitive AI-marketing audits') and provides an example question. It implicitly suggests using this tool over the sibling ai_visibility_check when comparing multiple entities, but does not explicitly mention when not to use it or list direct 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 readOnly, openWorld, idempotent, non-destructive. The description adds significant behavioral detail: fans out to external services, bundlephobia first measurement can take 5-30s, partial failures degrade gracefully with sources_failed reported. This enriches the agent's understanding 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, well-structured paragraph. It front-loads the purpose, then covers use cases, limitations, and return value. While slightly verbose, every sentence earns its place. Minor improvement could be breaking into bullet points for return structure, but current form is still highly readable.

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 (composite check, multiple services, partial failures), the description is remarkably complete. Without an output schema, it details the return structure explicitly. It also covers timing, failure modes, and ecosystem scope. No external documentation is needed for basic understanding.

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

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

Schema coverage is 100% with clear descriptions for both parameters (package name with scoped packages, version with default). The description adds no additional meaning beyond what the schema already provides.

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

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

The description explicitly states it's a composite check for npm packages, clearly distinguishing its purpose from sibling tools. It uses specific verbs ('check', 'fans out') and resources ('deps.dev', 'bundlephobia'). No sibling tool overlaps with this unique functionality.

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 ('is X safe / popular / small', 'what does adding lodash cost me'), notes ecosystem limitations (NPM only v1), and mentions alternative paths (PyPI/Maven etc. via deps.dev:version directly). It also warns about partial failures and timing.

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

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

Discloses the embedding model (BGE-base-en), similarity metric (cosine), chunking strategy (500-char overlapping windows), and a cap of 200K chars with truncation and flagging. Adds significant context beyond the annotations, which are already non-destructive and idempotent.

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?

A single paragraph of about 100 words, front-loaded with the core action, then providing usage guidance, technical details, and a pairing suggestion. Every 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?

Given no output schema, the description adequately explains the return format (top-N passages, character offsets, similarity scores). Also covers constraints (200K char cap) and integration with a sibling tool. No missing critical information.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the character cap on the 'text' parameter and hinting at the output structure (passages with offsets and similarity scores). Does not duplicate schema descriptions.

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

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

Clearly states the tool performs semantic search inside a fetched record, using a natural-language query to return relevant passages. Differentiates from sibling tools like ask_pipeworx_grounded by specifying the input (text already pulled) and output (passages with offsets).

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

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

Explicitly tells when to use: when the record is too large for the prompt. Mentions pairing with ask_pipeworx_grounded for a grounded workflow. Does not explicitly state when not to use, but the context is clear.

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

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

The description fully discloses behavioral traits beyond annotations. It specifies that the tool requires authentication (OAuth), that subscriptions persist, and details type-specific parameters. It also explains delivery channel behavior (always-on feed, optional email/SMS/webhook with constraints like SMS cap and webhook auto-disable). No contradiction with annotations (idempotentHint=true is reasonable for a create-with-upsert pattern described).

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

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

The description is well-structured, with the primary purpose front-loaded. Each section (requirements, types, delivery) is clearly separated. While slightly verbose, every sentence adds necessary context. A minor reduction could be achieved by combining some type examples, but overall it is efficient.

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

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

Given the moderate complexity (3 parameters, nested objects, multiple types), the description covers all essential aspects: purpose, authentication constraints, type-specific parameters, delivery options with constraints, return value (subscription id), and operational notes (webhook recovery). No output schema exists, but the return value is clearly stated. The tool is fully understandable without external references.

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 description adds extensive context beyond the input schema. For each subscription type, it provides concrete examples and explanations of parameters (e.g., 'sec_8k: {ticker:"AAPL", items?:["5.02","1.01"]}'). It also details nested delivery object properties (e.g., webhook signing, email validation, SMS verification). Since schema coverage is 100%, the description significantly enriches parameter understanding.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly states the action (subscribe), the resource (alerts), and the return value. It distinguishes the tool from siblings like list_subscriptions and unsubscribe by its creation role.

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 the requirement for a Pipeworx OAuth account, implying that anonymous or BYO users should not use this tool. It also details delivery channel constraints (e.g., SMS cap, phone verification), which guide appropriate usage. However, it does not explicitly contrast with list_subscriptions or unsubscribe, leaving some inference to the agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context about return structure (category-bucketed questions with tool+argument shapes) and notes it's a read-only discovery tool. 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 fairly long but front-loaded with purpose and usage. Every sentence adds value (purpose, categories, argument hint, usage directive). Could trim some parenthetical examples, but overall well-structured.

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

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

Despite no output schema, the description fully explains what is returned (example questions with tool calls) and covers both invocation patterns (no args vs. topic). For a discovery tool with one simple parameter and comprehensive annotations, this is complete.

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

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

Schema coverage is 100% (one parameter 'topic' described in schema). The description adds meaning by listing specific values ('finance', 'pharma', etc.) and explaining behavior when omitted ('full spread') vs. provided ('focus'). This goes beyond basic 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 uses specific verbs ('returns', 'draws from') and clearly identifies the resource ('onboarding entry point'). It distinguishes from siblings like 'ask_pipeworx' and 'discover_tools' by framing it as the initial exploration tool. The title 'What Can I Ask Pipeworx?' further reinforces 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?

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also provides guidance on optional 'topic' parameter to focus queries. This gives clear when-to-use and how-to-customize instructions.

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 non-read-only, idempotent, and non-destructive. Description adds ownership enforcement and clarifies that the row is deactivated not deleted, enhancing transparency beyond annotations.

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

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

Two concise sentences that front-load the action and efficiently add critical behavioral details without redundancy.

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

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

For a simple single-parameter tool with no output schema, the description fully covers purpose, restrictions, effect, and relationship to other tools like recent_alerts.

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 description for 'id'. The description adds that id is 'returned by subscribe', which provides helpful context beyond schema.

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

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

Clearly states the action ('cancel a subscription by id'), specifies the resource (subscription), and distinguishes from siblings like 'subscribe' and 'list_subscriptions' by detailing ownership enforcement and deactivation 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?

Explicitly notes ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when to use. Does not list alternatives or when-not cases, but the context is sufficient.

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

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

Annotations already declare safe, read-only, open-world behavior. The description goes beyond by detailing the two execution paths (SEC/EDGAR for financial claims, grounded pipeline for others), the use of exact percent-delta math, verbatim evidence, citation, and the full set of verdict values. 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 front-loaded with examples and usage guidance, then moves to technical details. Every sentence contributes; however, it is slightly verbose. Could tighten without losing clarity, but still 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?

Even without an output schema, the description explicitly states the return structure (verdict, value with citation, reasoning). It covers claim types, routing, tolerance behavior, and replaces multiple tool calls. Sufficient for agent understanding.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds context by explaining the tolerance_pct default, override use case ('set 1–2 for hallucination detection'), and claim examples. Further value beyond schema, though not exhaustive.

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

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

The description uses specific verbs ('validate', 'verify') and a clear resource ('natural-language claim against authoritative sources'). It explicitly distinguishes from siblings by stating it replaces 4–6 sequential calls and lists concrete query patterns. No ambiguity.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It provides examples of when to trigger and mentions internal routing for different claim types, giving strong guidance for selection.

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