Cfpb

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds value by specifying cost implications (BYO key for Anthropic), default model, and return structure (per-model {score, confidence, signals, raw_response} + combined view). No contradictions with annotations.

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

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

Three sentences: first states main action and return, second covers model options and cost, third lists use cases. No redundant information. Every sentence adds value.

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

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

No output schema, but description adequately covers return structure. It explains default model and optional Anthropic probing. Could mention parallel probing or response time, but overall complete for a probe tool with 4 parameters and good annotations.

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

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

Schema coverage is 100%, baseline 3. Description adds significant meaning: explains 'entity' as brand/business topic, lists model options, clarifies '_apiKey' for Anthropic pass-through, and 'context' for disambiguation. This goes beyond schema descriptions.

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

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

Description clearly states it probes LLMs for brand visibility and scores (0-100) per model. Verb 'probe' is specific, resource is LLMs, and it distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on entity-specific knowledge scoring.

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

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

Description explicitly lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and when to provide an API key for Anthropic. However, it does not explicitly state when NOT to use it or compare with alternative tools among siblings.

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

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

The description adds context beyond the annotations: it mentions the tool works on every tier, is 'one fast call', routes to many sources, and returns stable citation URIs. It also indirectly discloses potential hallucination risk by describing ask_pipeworx_grounded as 'hallucination-resistant', implying this tool may not be. This is rich behavioral disclosure beyond the readOnly/openWorld/idempotent hints.

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

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

The description is long but well-organized, with a clear preference directive, functional overview, usage triggers, examples, and escalation paths. Each sentence serves a purpose, though it could be slightly more concise given some repetition of 'START HERE' and 'works on every tier'.

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

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

Given the tool's complexity and lack of an output schema, the description is remarkably complete. It explains what it does, when to use it, what it returns (structured answer with citations), and how it relates to sibling tools. It leaves few gaps for an agent deciding whether and how to invoke it.

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

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

The schema covers 100% of parameters, including aliases for the 'question' field. The description does not add new parameter-level details beyond examples that are already present in the schema. It meets the baseline but does not exceed it.

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

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

The description clearly states that the tool routes questions to one of 5,529 tools across 1,455 verified sources, fills arguments, and returns structured answers with pipeworx:// citation URIs. It also distinguishes itself from sibling tools by naming ask_pipeworx_grounded and deep_research as alternatives.

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

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

It explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', provides specific trigger phrases ('what is', 'look up', 'find', etc.), and gives clear guidance on when to escalate to ask_pipeworx_grounded or deep_research. This is explicit when/when-not guidance with named alternatives.

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

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

Beyond the annotations (read-only, idempotent, etc.), the description discloses that this is an experimental edge with candidate routing improvements, that it currently matches the stable router, and that it is a full working router with no fallback. This provides valuable context about its current state and experimental nature.

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 long and front-loaded with the key identity ('Beta version of ask_pipeworx'). Each sentence adds useful information about current state, usage, and reassurance, though it could be slightly more concise.

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

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

The description fully covers what the tool is, its relationship to the stable version, its current experimental status, and how to use it. Given the absence of an output schema, it doesn't need to explain return values since they match ask_pipeworx. It's 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 has 100% coverage with descriptions for all parameters, including aliases. The description only mentions 'same arguments' without adding details, so it doesn't add much beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with 5,529 tools, and distinguishes it from the stable sibling by its experimental routing improvements. The verb 'ask' is implied, and it explicitly states it matches ask_pipeworx exactly when no candidate is active.

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

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

The description explicitly says to use it 'when you want the newest routing' and notes that results are compared against the stable router. This implies the alternative of using ask_pipeworx for stable routing, providing 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 mark it read-only, idempotent, and non-destructive; the description adds non-redundant behavioral details such as extraction only from tool result, explicit refusal reasons, and the cost delta. There is no contradiction with the annotations, and the refusal mechanism is a critical behavioral guarantee disclosed here.

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

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

The description is dense but extremely well structured: purpose, behavior, output shape, refusal semantics, when-to-use, and cost trade-off are all present. Every sentence contributes meaningful, non-redundant information, and the length is justified by the tool's high-stakes role.

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, high-stakes tool with no output schema, the description is remarkably complete. It provides the return shape, refusal reasons, use cases, routing relationship to ask_pipeworx, and the extra-call cost. No important behavior is left unexplained.

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

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

The input schema has 100% coverage: question and all five aliases are fully described. The description adds no extra parameter-level meaning beyond confirming the natural-language nature, so it fairly sits at the baseline for schemas that already do the heavy lifting.

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

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

The description uses a specific framing—'hallucination-resistant answer mode'—and clearly distinguishes itself from sibling ask_pipeworx by explaining shared routing plus the extra extraction step. It identifies the outcome (grounded answer or explicit refusal) with enough detail for an agent to know exactly what this tool does.

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

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

It explicitly states when to use this mode: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete examples. It also gives an exclusion and alternative: 'prefer ask_pipeworx for casual lookups' and quantifies the trade-off (one extra LLM call), which is exactly the guidance an agent needs.

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

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

The description extensively details behavioral traits beyond annotations: resolver contract with confidence levels, parent event extraction, news fallback mechanisms, safety short-circuits for low confidence, closed market handling, illiquid spread warnings, and resolution-rule risk. All consistent with annotations (readOnly, idempotent, non-destructive).

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

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

The description is very long and dense, but well-structured with clear sections (purpose, classifiers, fan-out examples, response shapes, resolver contract, etc.). It is not concise, but the structure helps readability. Still, it could be more streamlined.

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

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

The description is comprehensively complete for a tool with 3 parameters and no output schema. It details response shapes, error states (low confidence, closed markets, wide spreads), cancellation rules, and news behavior. Covers all edge cases a user needs to know for correct invocation and interpretation.

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

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

The input schema already provides complete descriptions for all three parameters (100% coverage), including examples, enums, and defaults. The description adds minimal new info beyond repeating parameter behaviors (e.g., depth defaults, include_raw summary). Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (Research), resource (Polymarket bet), and unique approach (one-call Pipeworx data pull). The tool is clearly differentiated from siblings like ask_pipeworx or polymarket_arbitrage by its specific focus on individual bet research.

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

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

The description provides explicit usage contexts: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives fan-out examples for different bet types. However, it does not explicitly state when not to use the tool or suggest alternatives, which would make it a 5.

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

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

Annotations mark the tool as read-only and safe, and the description adds behavioral context: it explains automatic normalization of common names to registered spelling, that the response will indicate the actual queried name, and that output includes narratives, company responses, and resolution details sorted newest first. This goes beyond basic safety to reveal how results may differ from the input.

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 with no redundant phrases. The first sentence provides an action-oriented summary; the second adds the most critical behavioral nuance (name resolution) and output details, each earning its place.

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

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

Given the robust annotations, output schema, and simple parameter set, the description covers the key use case. It could be enhanced by explicitly pointing to sibling tools (e.g., cfpb_search_complaints for broader searches), but it is still complete enough to select and invoke the tool correctly.

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

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

Both parameters are already described in the schema (100% coverage), so the baseline is 3. The description enriches the company parameter by revealing that everyday names are resolved automatically and that the response reports the actual queried name, which informs how to construct input. The limit parameter is sufficiently covered by 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 opens with a specific verb and resource: 'Get recent complaints against a specific company'. It provides concrete examples and clarifies the scope versus siblings (company-specific rather than generic search). It also mentions unique features like automatic name resolution, distinguishing it from cfpb_search_complaints or cfpb_get_complaint.

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 clearly implies the tool should be used when the agent needs complaints for a named company, and even gives example everyday names. However, it does not explicitly mention alternatives or state when not to use this tool, leaving a slight gap in exclusivity guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, etc., covering safety. The description adds behavioral context about the returned fields (narrative, company response, resolution, metadata), which is valuable beyond annotations.

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

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

Single sentence that front-loads the purpose and includes return details. Every word earns its place; no wasted information.

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

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

Given the tool's simplicity (1 param, output schema present), the description sufficiently covers purpose, usage context, and response contents. No gaps remain.

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

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

Schema coverage is 100% with a clear description for complaint_id. The description adds the phrase 'by ID', reinforcing the concept but not adding meaning beyond what the schema provides. 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 the verb 'retrieve' and resource 'complaint by ID', specifies return contents (narrative, etc.), and distinguishes from sibling tools like cfpb_search_complaints which are about searching, not individual retrieval.

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

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

The description implies usage when a specific complaint ID is known, providing clear context. However, it does not explicitly state when not to use it or mention alternative tools for broader searches, which would improve guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, so the safety profile is clear. The description adds that it retrieves counts, which is consistent. No additional behavioral details are needed for this simple read 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 a single sentence with an example, very concise and front-loaded. Every word adds value, no fluff.

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

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

For a low-complexity tool with 3 optional parameters, an output schema, and full annotation coverage, the description is mostly complete. It lacks mention of date dependency (e.g., both dates required together?) but overall is adequate.

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

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

Schema coverage is 100%, with each parameter described in the schema. The description reiterates filtering by company or date range but does not add new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns complaint counts by product category, with examples like 'Credit Card' and 'Mortgage'. It distinguishes from siblings like cfpb_company_complaints by focusing on product breakdowns, though it does not explicitly contrast with them.

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

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

No guidance on when to use this tool versus alternatives like cfpb_company_complaints or cfpb_search_complaints. The description only states filtering options, not selection criteria, leaving the agent to infer context.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by specifying the returned data (complaint narratives, company responses, resolution status), which 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 a single efficient sentence that front-loads the action and key filters. No superfluous text.

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

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

The description covers the core functionality and output types. With an output schema present, it does not need to elaborate return values further. However, it omits details like pagination or rate limits, which are not critical given the annotations.

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 itself documents all parameters thoroughly. The description does not add additional semantic meaning beyond summarizing the filter options already in the schema.

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

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

The description clearly states the tool searches consumer complaints by multiple criteria (keyword, company, product, date range) and returns specific output (narratives, responses, resolution status). It distinguishes from sibling tools like cfpb_company_complaints and cfpb_get_complaint.

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

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

No guidance on when to use this tool versus siblings such as cfpb_company_complaints or cfpb_product_breakdown. The description does not mention alternatives or exclusionary cases.

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=true, idempotentHint=true, destructiveHint=false. Description adds that output is a ranked list with company names and counts, which is useful but does not disclose potential pagination, maximum limit, or error conditions. 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 redundancy. First sentence states action and scope; second sentence specifies output. Every word is necessary and front-loaded.

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

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

Given that output schema exists and annotations are comprehensive, the description is nearly complete. It covers the core purpose and result format. Minor improvement would be to explicitly mention descending order by count, but 'most complaints' implies ranking, so this is sufficient.

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

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

Schema description coverage is 100%, so the schema already describes all parameters. Description reinforces that date range is used (start_date, end_date) but does not add new meaning beyond stating the tool's purpose. Baseline 3 is appropriate.

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

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

Description uses specific verb 'find', identifies resource 'companies with the most complaints', and specifies time scope 'in a date range'. It clearly differentiates from siblings like cfpb_search_complaints (search individual complaints) and cfpb_product_breakdown (breakdown by product) by focusing on ranking companies by complaint volume.

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

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

Description does not explicitly state when to use this tool versus alternatives or provide exclusions. The purpose is implied but lacks guidance such as 'use this to identify top complaint recipients' or 'for individual complaint details, use cfpb_get_complaint'.

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, openWorld, idempotent, non-destructive. Description adds rich behavioral details: pulls latest 10-K data from SEC EDGAR/XBRL, handles off-calendar fiscal years, sorts results by primary metric, returns paired data with citation URIs. Differentiates behavior for companies vs drugs.

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 dense paragraph with front-loaded purpose and example queries. Slightly verbose with repeated query patterns, but every sentence adds value. Could be slightly more concise.

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 2 parameters, no output schema, and comparison context, description covers types, data sources, sorting, return format, and citation URIs. Provides sufficient information for an agent to correctly select and invoke the tool.

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

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

Schema has 100% coverage with descriptions for both parameters. Description adds significant meaning beyond schema: explains what data is pulled per type (revenue, net income, cash, debt for companies; adverse events, approvals, trials for drugs) and specifies that values should be tickers/CIKs or drug names.

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 performs side-by-side comparison of 2–5 entities (companies or drugs) in one parallel call. Uses specific verbs like 'compare', 'rank', 'head to head' and distinguishes from sequential single-pack lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'. Provides example queries. Could be improved by naming alternative sibling tools (e.g., entity_profile), but still 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?

Beyond annotations, the description reveals decomposition into facets, parallel routing to 5,529 tools, the findings packet structure (gaps[], contradictions[], hop, citation_uri), semantic excerpting behavior, and expected latency. It also states the tool 'never invented' answers and clarifies the citation resolvability condition, adding rich behavioral context.

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

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

The description is long (approx. 250 words) but front-loaded with account requirements, fallback, and core function. Every sentence delivers operational information, though a few redundancies (e.g., 'not open-web search' appears twice) could be trimmed. Given the tool's complexity, the length is mostly justified.

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

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

Without an output schema, the description fully compensates by specifying the return findings packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[] for unanswered facets, contradictions[] for standard/thorough, and precise timing limits. It also covers edge cases like news topics returning empty results, making the tool's behavior highly predictable.

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

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

Schema already covers 100% of parameters, but the description adds significant meaning: depth levels are explained with behavioral differences (quick/standard/thorough, paid plan requirement, gap-recovery hops), and the question parameter is clarified as being natural language and broad/multi-part, reinforcing the schema's minimal 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 performs 'multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, explicitly noting it is not open-web search. This distinguishes it from siblings like ask_pipeworx, and uses a specific verb+resource construction.

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?

Usage guidance is explicit: 'Best for broad/multi-part questions over structured data', with directives to use ask_pipeworx for single lookups and breaking news, including the reason why (returns empty gaps). It also provides an account fallback instruction, making use-cases and exclusions crystal 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. The description adds that results include full input schemas with examples and are ready to call directly, enhancing transparency without contradiction.

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

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

The description is two sentences, front-loaded with purpose, and every word adds value. No fluff.

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

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

For a simple tool discovery function, the description explains what it returns (top-N tools with schemas) and how to use it. No output schema is needed as the return format is described. Complete given low complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions aliases for query, which is already in schema docs, and provides example queries, adding some value but not significantly beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides concrete examples (SEC filings, FDA drugs, etc.) and distinguishes itself as the primary tool for discovering other tools among the siblings.

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

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

The description explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear usage context, though it doesn't explicitly state when not to use it.

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

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

Beyond annotations (read-only, open world, idempotent), the description details the multiple data sources contacted (SEC EDGAR, XBRL, USPTO, news, GLEIF), specific returned fields, and known limitations (patent source sunsetting in May 2025 with soft-fail). This provides comprehensive behavioral transparency without contradicting annotations.

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

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

The description is well-structured with example queries at the beginning, followed by details of what is returned. While it is somewhat lengthy, every sentence provides useful information. A slight reduction in redundancy could improve conciseness.

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

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

Given the complexity of fetching data from multiple sources, the description fully explains the output including specific fields, URIs, fallback behavior, and temporal notes (patent sunset). With only 2 parameters and no output schema, the description provides complete context for an agent to correctly invoke the tool.

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

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

Schema coverage is 100% with descriptions for both parameters, but the description adds significant value by providing example values (ticker or zero-padded CIK), clarifying that names are not supported, and noting that only 'company' type is currently available. This enriches the schema explanation.

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 like 'tell me about', 'research', 'brief me on' and clearly identifies the resource as a full cross-source profile of a US public company. It distinguishes from siblings such as resolve_entity and compare_entities by emphasizing that this tool provides a holistic view in one parallel call.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies that names are not supported and directs to use resolve_entity first, 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. Description adds context about clearing sensitive data but doesn't go beyond what annotations convey.

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

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

Three concise sentences, front-loaded with the action. No wasted words.

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

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

Given the single parameter and no output schema, description fully covers purpose, usage, and relationship to siblings. Complete for a simple deletion 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%. Description adds no extra meaning beyond the schema's key parameter 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?

Description clearly states 'Delete a previously stored memory by key'. It distinguishes from siblings (remember, recall) by mentioning pairing with them.

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

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

Explicitly states when to use: when context is stale, task is done, or to clear sensitive data. Also suggests pairing with 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, openWorldHint, idempotentHint, and non-destructive nature. The description adds transparency by detailing the process (fetching the page, extracting info) and the output format (single text blob for site-root/llms.txt), providing context beyond annotations.

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

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

The description is two concise sentences followed by a list of use cases. It is front-loaded with the core purpose and immediately provides context. No redundant or unnecessary 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?

For a simple tool with only two parameters and no output schema, the description fully explains the purpose, process, output format, and use cases. Annotations cover safety and idempotency, so the description 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?

All parameters (url, max_links) are fully described in the input schema with 100% coverage. The description does not add new semantic meaning beyond what the schema provides, meriting the baseline score.

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

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

The description clearly states the tool generates a production-ready llms.txt file for a given URL, with specific actions (fetches page, extracts title/description/key links, emits markdown). This distinguishes it from siblings, none of which perform the same task.

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

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

The description lists explicit use cases (getting a client's site indexed, drafting your own llms.txt, auditing competitor AI visibility) but does not provide guidance on when to avoid using this tool or suggest alternative tools. However, the use cases are clear and relevant.

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 and idempotentHint. Description adds return structure but no new behavioral traits beyond confirming read-only nature.

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

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

Two sentences, front-loaded with purpose, then returns and usage. 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?

Simple tool with one optional param and clear output described. No gaps for an agent to use correctly.

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

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

Schema coverage is 100% with description for include_inactive. Description does not add further meaning beyond what the schema provides.

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

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

Clearly states 'list the caller's active subscriptions' and specifies returned fields. Distinguishes from siblings like subscribe and unsubscribe.

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

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

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

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

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

Annotations are all false (readOnlyHint: false, etc.), so the description carries the full burden. It discloses key behaviors: filing without an account returns a claim_token, passing the token later reads status and resolution, rate-limited to 5 per identifier per day, free and not counted against tool-call quota, daily digests read by the team. This goes well beyond annotation hints.

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

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

While the description is long, every sentence earns its place. It covers purpose, usage scenarios, exclusions, feedback composition, claim_token behavior, rate limits, and quota impact in a logical flow. There is zero redundancy or fluff; each sentence adds distinct value.

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

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

Given the params, nested objects, enum, and lack of output schema, the description is remarkably complete. It explains the feedback type system, context object usage, claim_token mechanics, rate limiting, and scope. The schema documents parameters thoroughly, and the description fills in operational context, making the tool fully understandable without an output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful usage context for parameters, particularly telling the agent to 'Describe the issue in terms of Pipeworx tools/packs' and warning not to paste the end-user's prompt. It also explains the claim_token lifecycle, which complements the schema's description. These additions elevate it above baseline.

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

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

Description starts with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly defines the tool's purpose and differentiates it from sibling tools like ask_pipeworx and ask_pipeworx_beta by focusing on feedback about Pipeworx's own tools, not general questions. The scope is explicitly limited to tools served by this Pipeworx connection, making it distinct.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also includes a clear when-not-to-use exclusion: 'if the tool came from a different MCP server ... file it with that server instead.' This directly guides tool selection versus alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds important behaviors: self-aggregating from CF analytics-engine, no PII, caching policy (5min-1h). 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?

Paragraph format with clear bullet-like list of use cases. Efficiently covers purpose, behavior, and guidance without extra 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, but description fully explains return values (top tools, packs, volume). Also covers data source, privacy, and caching. Complete for its 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 has 100% coverage with enum and description for window. Description adds practical nuance: shorter windows for hot trends, longer for steady-state. Provides value beyond schema.

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

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

Clearly states it returns top tools, top packs, and total call volume over three time windows. Distinct from sibling tools like ask_pipeworx or discover_tools, making its unique purpose clear.

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

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

Explicitly lists three use cases: discovering hot data sources, confirming canonical tool, and checking alignment. Lacks explicit 'when not to use' but provides strong contextual guidance.

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

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

The description thoroughly exposes the tool's behavior beyond annotations: it details the algorithms (monotonicity, partition check), filtering criteria (Jaccard similarity, placeholder fraction), and the fill check logic. The annotations (readOnlyHint, idempotentHint) are consistent with the description, and no contradictions exist.

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 verbose but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose. Each sentence adds substance, though some detail (e.g., exact Jaccard threshold) could be considered excessive 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 complexity, the description fully covers functionality, invocation modes, algorithm details, filtering, response structure (opportunities[]), and crucial caveats like the fill check. It compensates for the lack of an output schema by describing the response shape, making it complete 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?

Both parameters have full schema descriptions (100% coverage), and the description adds significant value by explaining their purpose, acceptable values (e.g., 'event slug like "fed-decision-may-2026"'), and how the mode changes behavior. This goes beyond the schema's minimum.

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

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

The description clearly states that the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes: no-arg trending scan, event-specific scan, and cross-event topic scan, setting it apart 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?

The description explicitly instructs when to use each mode: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also provides guidance on the fill check and recommends polymarket_fill_risk for custom sizing, effectively directing the agent to alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral details: caching at KV level keyed on all knobs, model specifics (e.g., lognormal barrier, GDELT), diagnostics showing why segments may be empty, and 24h-move warnings. No contradictions with annotations.

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

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

The description is very long and dense, front-loading purpose but then delving into detailed model explanations. While it contains valuable information, it could be more concise and structured with bullet points or sections 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 9 parameters, no output schema, and the tool's complexity, the description is comprehensive. It explains the response structure (by_segment, diagnostics), tradeable-edge knobs, and edge cases (Fed bets, cache duration, filter_skips).

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

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

Input schema covers 100% of parameters with descriptions. The tool description adds significant context beyond the schema: e.g., for slippage_pp it explains Polymarket fees and recommends adjustments; for min_kelly it clarifies it applies to single-leg opportunities; for min_partition_leg_kelly it explains why partition arbs have kelly_fraction_half=0. This adds practical usage guidance.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It details three specific segments (model_driven, structural_arbitrage, concentrated_longshot), differentiating it from sibling tools like polymarket_arbitrage.

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

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

The description explicitly states the tool is 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It provides guidance on tradeable-edge knobs (min_liquidity, max_spread_pp) and explains response structure, though it does not explicitly state when not to use or compare to alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, etc. The description substantially adds behavioral traits: it reads snapshots, returns a time-series for edge_pp_net, computes first_seen, trend, decay_pp_per_day, and limits (60-day TTL, daily closes not intraday). No contradiction with annotations; full transparency.

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

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

The description is front-loaded with the core purpose question, then systematically explains response fields and limits. Every sentence adds unique information without redundancy. Despite length, it earns its space through clear structure and useful detail.

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

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

Given no output schema, the description thoroughly explains all return values (tracked[], expired[], snapshot_dates[]) with field meanings and examples (e.g., trend categories, decay computation). Limits and edge cases are covered. The description is complete for a tool with two simple parameters.

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

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

Schema coverage is 100%, so baseline is high. The description adds value beyond the schema: it provides default values (14 days, '1wk'), explains the meaning of each parameter (lookback, snapshot family), and adds context for window (e.g., '24hr | 1wk | 1mo'). This enriches understanding.

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

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

The description clearly states the specific verb+resource: 'Edge persistence and decay telemetry' built from snapshots. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical analysis and signal decay. The core question 'how long has this edge existed and is it shrinking?' precisely captures the tool's unique purpose.

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

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

The description implies when to use this tool (when edge age and decay matter) but does not explicitly contrast with alternatives like polymarket_edges or polymarket_arbitrage. The phrase 'a fresh wide edge and a 3-week-old wide edge are different trades' provides strong usage context, but explicit 'use this when, use that when' guidance is missing.

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 goes beyond by detailing return fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.) and the critical risk that partial basket fills create unhedged directional positions. 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 fairly long but well-structured with section headings (SINGLE-MARKET, BASKET) and bold emphasis on key terms. Every sentence adds value, though minor redundancy exists (e.g., 'default auto' explained twice). Still, it's efficient for 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?

Given two modes, four parameters, no output schema, and high complexity, the description is remarkably complete. It explains what each mode returns (including per-leg detail, thin_legs, max_clean_notional_usd, forced_directional_risk) and addresses the dominant loss mode (partial fills). An agent can correctly select and invoke this tool.

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

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

Schema coverage is 100%, baseline 3, but the description adds substantial meaning: explains the two distinct interpretation of size_usd (spend/target vs. settlement notional), the auto-detection of side for baskets, and the difference between market and event parameters. This is far more than the schema provides.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth', a specific verb+resource combination that immediately distinguishes it from siblings like polymarket_arbitrage and polymarket_edges. The two modes (single-market and basket) are clearly delineated.

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 before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', providing clear when-to-use context. Also warns about partial basket fills converting an arb into an unhedged directional position, effectively telling when not to proceed.

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

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

The description goes well beyond the annotations by detailing compatibility warning conditions, temporal alignment field, and skipped cross type/subtype counters. It explains that the tool may return no matching pairs if bet shapes are not equivalent, adding crucial behavioral context. Annotations already indicate read-only, idempotent, non-destructive, and open-world, and the description reinforces and extends this.

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

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

The description is comprehensive but somewhat lengthy; it could be better organized with separate sections for modes, response, and safety. However, it front-loads the core purpose and avoids irrelevant fluff. Every sentence adds information, but some repetition (e.g., explaining modes twice) slightly reduces conciseness.

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

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

Given the tool's complexity (two modes, safety fields, temporal alignment, cross-venue comparisons), the description covers all critical aspects. Even without an output schema, it describes the response structure and how to interpret safety fields. It addresses edge cases like non-equivalent bet shapes and temporal mismatches, ensuring the agent has sufficient context 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 parameters are defined in the schema. The description adds value by explaining the two modes and how explicit tickers override topic shortcuts. Examples are provided in the schema's examples array. However, the description could have elaborated further on the exact format requirements for tickers, but it is adequate.

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 two modes (topic shortcuts and explicit tickers) and explains the response structure. The name and title are consistent, and it differentiates from sibling tools like 'polymarket_arbitrage' by focusing on cross-venue spreads.

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

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

The description provides explicit guidance on when to use each mode, warns that most pre-mapped topics return compatibility warnings, and explains that spreads are only meaningful when temporal alignment is true. However, it does not explicitly state when the tool should not be used, though the warnings imply conditions to avoid.

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

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

Annotations already declare readOnlyHint and idempotentHint; description adds scoping to user identifier (anonymous IP, key hash, or account ID) and the listing behavior when key is omitted. 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?

Three sentences, each serving a clear purpose: purpose, usage guidance, and scoping/pairing. No wasted words, front-loaded, tightly written.

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

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

No output schema, but description hints at return types (value or list of keys) and explains scoping. For a simple read-only tool, this is nearly complete. Could mention data type of values, but not critical.

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 description of the key parameter. Description adds context about omitting key to list all keys, which reinforces schema but adds usage clarity. Baseline 3, improvement for explicit omit behavior and examples.

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 retrieves a saved value or lists all keys (verb+resource). Explicitly distinguishes from siblings (remember, forget) by naming them.

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

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

Provides concrete examples (user's target ticker, address, research notes) and explains when to use: to look up context stored earlier, avoiding re-derivation. Also references alternative tools (remember, forget).

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=true, idempotentHint=true, destructiveHint=false) are consistent with the description's 'Pull' and 'flag returned events read' language, which is non-destructive. The description adds value by disclosing that events carry specific fields (source, citation_uri, raw payload) and that the feed is available via a separate GET endpoint. No contradictions.

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

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

The description is a single efficient paragraph. It front-loads the main action and then adds necessary details without redundancy. Every sentence contributes meaningful 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?

All five optional parameters are covered, return value fields are described (source, citation_uri, raw event payload), and usage patterns (polls, direct GET) are mentioned. Despite no output schema, the description is sufficient 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?

Input schema has 100% description coverage for all 5 parameters. The description enhances meaning by providing examples ('sec_8k') and explaining the behavioral effect of mark_read ('so the next call only shows newer ones'). This goes beyond the schema's basic descriptions.

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

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

The description opens with 'Pull fired events from your subscription feed', which is a specific verb+resource combination. It clearly distinguishes this tool from siblings like 'list_subscriptions' (which lists subscriptions, not events) and 'subscribe' (which creates subscriptions). The purpose is 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 explains filtering by type and/or since timestamp, and how mark_read affects subsequent calls. It also mentions that polling works fine and that the same feed is available via a direct GET URL for scripts/dashboards, providing an alternative. No explicit when-not-to-use guidance, but otherwise clear usage context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral details: fans out to multiple sources, fallback from GDELT to GNews, and soft-fail for USPTO due to API sunset. No contradiction with annotations.

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

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

The description is information-dense but not overly long. It's front-loaded with examples and structured logically. A slight reduction could improve conciseness, but it remains clear and 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?

Despite no output schema, the description fully explains the return format: structured changes grouped by source, total_changes count, and citation URIs. It also covers edge cases like fallback and sunset, making it complete for a complex tool.

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

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

All parameters are described in the schema with 100% coverage. The description adds extra semantics: 'since' accepts relative shorthand like '7d', '30d', '3m', '1y', and 'value' can be a ticker or CIK. This enhances understanding beyond the schema.

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

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

The description clearly states it's a change feed for a company within a time window, lists specific sources (SEC EDGAR, GDELT→GNews, USPTO), and distinguishes from the sibling tool entity_profile, which provides a static profile. Examples of queries align with the tool's purpose.

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

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

The description explicitly tells when to use this tool (for recent changes) and when not ('Use entity_profile instead when you want the static profile'). It also provides example queries and a note about rate limits and fallback behavior.

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

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

Describes storage as key-value pair scoped by identifier, persistence details (authenticated vs anonymous, 24-hour retention). Adds value beyond annotations.

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

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

Four sentences, front-loaded with purpose, no wasted words. Every sentence contributes clear 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?

Fully covers the tool's behavior, scope, and lifecycle for a simple write operation. 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 already covers both parameters with descriptions. Description adds examples of key patterns and value types, enhancing meaning.

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

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

Clearly states 'Save data' with specific verb and resource. Distinguishes from siblings 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?

Explicitly describes when to use (discover something worth carrying forward) and provides examples like resolved ticker, target address. Mentions pairing with recall and forget.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds significant behavioral context beyond that: it cascades through multiple lookup endpoints, labels each identifier with its source, reports unresolved identifiers explicitly under an `unresolved` field, and degrades gracefully when GLEIF/OpenFIGI are down. This gives the agent a clear picture of side effects and safety.

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 purpose and examples, then provides structured detail on supported types and fallback behavior. It is somewhat long and dense with parentheticals, but every sentence adds meaningful information. It could be tightened, but it is not bloated.

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

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

With no output schema, the description carries the burden of explaining what is returned: it lists the identifier types, source labels, unresolved handling, and graceful degradation. It also explains the multi-call cascade behavior and positions the tool as replacing manual lookups. This is complete for an agent to invoke correctly and interpret results.

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

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

Schema coverage is 100%, so the schema already documents `type` and `value` including examples. The description enhances this by giving concrete examples (AAPL, 0000320193, ozempic) and clarifying that `company` accepts ticker, CIK, or name, while `drug` accepts brand or generic. This is a small but useful addition over 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 opens with explicit natural-language examples of user queries, then states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It names the specific resources (SEC EDGAR CIK, GLEIF LEI, OpenFIGI FIGI, RxNorm RxCUI) and clearly distinguishes itself from siblings by saying 'Use FIRST whenever you have a name but need an ID.'

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

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

The description gives direct usage guidance: 'Use FIRST whenever you have a name but need an ID.' It provides concrete query examples and explains graceful degradation fallback, so an agent knows to use the tool even if some enrichment sources are unavailable. It doesn't explicitly list when-not-to-use, but the 'Use FIRST' directive is strong enough to set the selection rule.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds that it probes each entity with ai_visibility_check and returns score, confidence, signal density. It does not contradict annotations but does not add significant behavioral detail beyond what is implied.

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

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

Three sentences, front-loaded with the core purpose, followed by mechanism and use case. No wasted words.

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

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

The description explains the overall function, how it works, and the output structure. Given the presence of a full input schema and no output schema, it is complete enough for the agent to use effectively.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by clarifying that the first entity is treated as the 'subject' and the rest as competitors, which is not in the schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check to probe each entity, and returning a ranked list. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (likely other comparisons).

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 it is 'useful for competitive AI-marketing audits' and gives an example. It implies that for a single entity one would use ai_visibility_check, but does not explicitly state when not to use or list alternatives.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds valuable context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed list for timeouts. No contradictions.

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

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

Description is verbose but efficient, front-loading the main purpose. Every sentence adds value, but could be slightly more concise. Still 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 explains the return format (summary block, advisories, links, alternative versions), covers partial failures, ecosystem limitations, and performance notes. Complete for the tool's complexity.

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

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

Schema provides 100% coverage for both parameters (package and version). Description adds minimal extra (scoped packages accepted, version defaults to latest) but mostly repeats schema info. 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 as a composite check for evaluating npm packages, specifying it fans out across deps.dev and bundlephobia. It distinguishes from siblings by focusing on npm ecosystem and specific metrics.

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 agent asks 'is X safe/popular/small' or 'what does adding lodash cost me'. Also notes ecosystem scope (npm only) and directs alternative ecosystems 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?

Annotations already declare safety; description adds truncation (200K chars, flagged), embedding model, window size, similarity metric, offset info. No contradiction.

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

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

Front-loaded with purpose, then usage, then technical details. Every sentence adds value; no fluff.

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

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

Despite no output schema, description explains return format (passages with offsets and scores) and handles edge case (truncation). Complete for a search tool.

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

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

Schema coverage 100%; description adds practical context like max chars for text, example queries, limit range and default, 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?

Clearly states the tool performs semantic search inside a fetched record, distinguishing it from siblings like ask_pipeworx_grounded. Uses specific verbs and resources.

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

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

Explicitly advises when to use ('when the record is too big to cram into the prompt') and pairs with another tool. Lacks explicit when-not scenarios, but context suffices.

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

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

Beyond annotations (idempotent, non-destructive, non-read-only), the description details required account type, delivery channels with constraints (email verification, SMS cap, webhook signing and auto-disable), and the fact that the feed is always on. 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?

Every sentence adds essential information. The description is front-loaded with the core purpose and flows logically into prerequisites, types, and delivery. 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 the tool's complexity (multiple types, delivery options), the description covers all necessary aspects: purpose, prerequisites, type-specific parameters, delivery options and their constraints, and the return value. It is complete for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline 3. The description adds value by explaining the purpose of each subscription type and providing concrete parameter examples, enhancing the bare schema descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description specifies prerequisites (Pipeworx OAuth account) and supported types with examples, guiding when to use each type. It implicitly differentiates from other tools but lacks explicit 'when not to use' or direct comparison to alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral details about the return format (category-bucketed example questions with exact tool+argument shape), 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 concisely structured, front-loading the purpose and common phrasings, followed by a list of category topics and usage instructions. Every sentence adds substantial value without redundancy.

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

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

Given the lack of an output schema, the description comprehensively explains the return content (category-bucketed questions with tool+argument shape). It fully covers purpose, usage, and parameter semantics, making the tool self-explanatory in context.

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

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

Schema coverage is 100% with a clear description of the topic parameter. The description significantly enhances this by explaining the effect of omitting vs. providing the parameter, listing acceptable focus areas, and noting that the full spread is returned without arguments.

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 the onboarding entry point for a newly connected agent, returning category-bucketed example questions. It distinguishes itself from sibling tools like ask_pipeworx by focusing on providing ideas for what to ask, rather than executing a query.

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 the agent to use this tool first when unsure of Pipeworx's capabilities and to learn how to call meta-tools. Provides guidance on calling with no arguments vs. passing a topic to focus, giving clear when-to-use context.

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

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

The description adds behavioral context beyond annotations: it explains that the row is deactivated (not deleted) and that ownership is enforced. This supplements the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) without contradiction.

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

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

Two sentences, zero wasted words. The description is front-loaded with the main action and then provides key behavioral traits concisely.

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

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

Given the tool's simplicity (1 parameter, no output schema, annotations present), the description is complete. It covers what the tool does, constraints (ownership), and outcome (deactivation, history availability). No missing 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?

The input schema already describes the 'id' parameter with 100% coverage. The description does not add new semantic details about the parameter itself, but it provides context about ownership and deactivation that indirectly relates to how the parameter is used. 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 uses specific verb 'cancel' and resource 'subscription by id', clearly distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'. It also explains the outcome (deactivation) and ownership enforcement, which adds clarity.

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 ownership enforcement ('you can only cancel your own subscriptions'), which guides usage. It also mentions that historical events remain available via 'recent_alerts', providing a clear alternative for accessing history. However, it does not explicitly state when not to use this tool.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral detail beyond that: the exact verdict values, the meaning of the two failure modes (could_not_verify, unsupported), the presence of verification_error with stage/detail, the warning that could_not_verify must not be treated as evidence, and the pipeline mechanics (percent-delta math, grounded sources, verbatim evidence with citations).

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: example phrasings first, then usage, then pipeline details, return values, and caller warnings. Every sentence contributes value. It could be slightly tightened (e.g., trimming example lists), but the length is justified by the tool's complexity, and the front-loading 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?

Given no output schema, the description fully accounts for return values (verdict set, grounded/structured actual value, citation, reasoning), error handling (could_not_verify with verification_error), the unsupported case, and its role as a single-call consolidation of 4–6 steps. It leaves no critical ambiguity for an agent deciding or invoking the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantic guidance for both parameters: example claim formats for the claim field and the tolerance_pct's role as an override (with the 1–2 recommendation for hallucination detection and default behavior). This extra context merits 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 a specific verb+resource: natural-language claim verification against authoritative sources. It provides multiple example user phrasings, distinguishes its scope (company-financial vs other fact checks), and explicitly frames itself as a replacement for 4–6 sequential calls, differentiating it from sibling tools.

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

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

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes internal routing (SEC EDGAR fast path for financial claims vs grounded pipeline for anything else), giving clear context. However, it does not explicitly name alternative tools or say when not to use it, so it falls just short of a 5.

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