Census Trade

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds critical context: default model (Workers AI Llama), API key requirement for Anthropic, and output format (per-model score, confidence, signals, raw_response + combined view). 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 paragraph with front-loaded action and key details. It is concise and covers all essential aspects, though a slightly more structured format (e.g., bullet points) could improve readability.

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

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

Given no output schema, the description adequately explains the return format and main use cases. It covers required and optional parameters. It lacks error handling or limitations, but for a probe tool it is reasonably complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the default model and the role of `_apiKey` (BYO key, direct payment). It also describes the return structure, which is not in the schema. This extra context justifies a 4.

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

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

The description clearly states the verb 'probe', the resource 'LLMs', and the output 'score visibility (0-100)'. It distinguishes itself from sibling tools like 'ask_pipeworx' by focusing on visibility scoring rather than general Q&A.

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

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

The description provides clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the API key for Anthropic. However, it lacks explicit 'when not to use' guidance or comparison to alternative tools like 'deep_research'.

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 (readOnlyHint, idempotentHint, etc.), the description reveals it fills arguments, routes to one of many sources, and returns stable pipeworx:// citation URIs. It also mentions it works on every tier and is one fast call, adding operational context not available in annotations.

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

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

Front-loaded with the key directive ('PREFER OVER WEB SEARCH') and uses clear, distinct sections for purpose, usage, examples, and alternatives. Slightly verbose with some redundant phrases ('START HERE', 'default entry point', 'one fast call'), but every part contributes to guiding the agent.

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

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

Given no output schema, the description sufficiently explains the return format (structured answer with citation URIs) and covers when to use, alternatives, examples, and behavior across scenarios. The complexity of routing across thousands of tools is clearly addressed, making the tool complete for an agent.

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

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

Schema description coverage is 100% for all six parameters (all aliases for 'question'), so the baseline is 3. The description's question examples illustrate intended values but add no new parameter semantics beyond what the schema already documents.

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 answers questions by routing to one of 5,439 tools across verified sources and returns a structured answer with citations. It explicitly distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research, making its scope precise.

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

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

Provides extensive guidance: 'PREFER OVER WEB SEARCH', triggers like 'what is', 'look up', 'find', concrete examples, and explicit step-up alternatives for grounded answers or deep research. Also covers edge cases like breaking news and mentions it's the default entry point.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond those: it is a fully working router with no fallback, candidate routing improvements are only active while under test, and none is active as of the stated date. No contradiction with annotations.

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

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

Four sentences, front-loaded with the beta status and equivalence to ask_pipeworx. Every sentence provides useful context, though the date and the fallback clarification make it slightly longer than strictly necessary.

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 the tool's experimental nature, current state, usage, and relationship to the stable router. Since there is no output schema, it references the same response shape as ask_pipeworx, which relies on sibling knowledge but is acceptable given the explicit comparison.

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

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

Schema coverage is 100%, with the required 'question' field and five explicitly described aliases. The description only says 'same arguments' as ask_pipeworx, which adds no new parameter-level information, but it doesn't need to because the schema fully documents all parameters.

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

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

Clearly identifies itself as the beta variant of ask_pipeworx, a universal router over 5,439 tools, and distinguishes from the stable ask_pipeworx by noting it is the experimental edge. It explicitly states that it currently matches ask_pipeworx exactly, making the purpose and scope unambiguous.

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

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

Provides explicit guidance: use it exactly like ask_pipeworx when you want the newest routing, and explains that results are compared against the stable router. The alternative tool is named, and the current state (no active candidate) clarifies when it behaves identically.

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 discloses the return format (answer, evidence, confidence, source, fetched_at), explicit refusal reasons (not_in_source, no_tool_match, etc.), the fact that it uses only tool result content, and the extra LLM call overhead. This significantly exceeds the safety and behavior info provided by readOnlyHint/interaction 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 dense but every sentence earns its place. It front-loads the core purpose, then explains behavior, return format, usage guidance, and trade-offs—no fluff or repetition. The structure flows logically from 'what' to 'how' to 'when'.

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 (grounded answering with refusal semantics) and the lack of an output schema, the description is remarkably complete. It covers success and refusal return shapes, all refusal reasons, routing details, use cases, and cost trade-offs, making it fully sufficient for an agent to decide when to use the tool and what to expect.

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

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

The input schema already covers all 6 parameters (aliases for 'question') with 100% description coverage, so the baseline is 3. The tool description does not add meaning beyond the schema—it mentions 'fills arguments' but that's internal routing, not user parameter guidance. The user-facing parameter semantics are fully 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 identifies this as a 'hallucination-resistant answer mode' for high-stakes reads, with a specific verb (ask) and resource (Pipeworx). It distinguishes from sibling ask_pipeworx by emphasizing grounded extraction using only tool results, making the purpose unambiguous.

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

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

Explicitly states when to use ('Use whenever an answer will be quoted, cited, or acted on...') and when not to ('prefer ask_pipeworx for casual lookups'), with concrete examples of high-stakes domains. Also names the alternative tool and notes the extra LLM call cost.

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

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

Annotations indicate read-only and idempotent. The description goes well beyond by detailing fan-out behavior, safety mechanisms (low-confidence short-circuits, closed markets), cancellation rules, and response shapes. 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 lengthy but well-structured with clear sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Front-loaded with main purpose. Every sentence adds value, but could be slightly more concise without losing information.

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

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

Given no output schema, the description thoroughly explains return values (market, analysis, evidence) and covers edge cases (low-confidence, closed markets, wide spreads, cancellation rules). Complex tool with sufficient depth 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%, providing baseline at 3. The description adds substantial value: explains market parameter accepts slug, URL, or question text; describes depth enum with defaults; details include_raw boolean with usage guidance. Exceeds 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?

The description clearly states the verb 'research' and the resource 'Polymarket bet', specifying it pulls Pipeworx data in one call. It distinguishes from sibling tools like polymarket_arbitrage by focusing on research rather than trading or edge tracking.

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

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

The description explicitly lists use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. While it doesn't directly compare to siblings, the context implies it's for research. Lacks explicit when-not-to-use but provides strong 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 provide safety profile (readOnly, idempotent, non-destructive). The description adds value by stating return contents (values, quantities, commodity details) and clarifying that plain English country names are resolved for the user. No contradictions with annotations.

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

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

Two sentences with no filler. The first sentence states purpose and returns; the second provides essential usage instructions. Front-loaded and efficient.

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

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

The description covers the primary usage variants and return content. With an output schema present and annotations covering safety, the description is sufficient for an agent to invoke the tool correctly. Remaining parameters (month, limit, country_code) are already explained in the 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 aggregation semantics: omitting `hs_code` gives total exports to a country, omitting `country` gives all countries combined. This goes beyond the schema's optional flags and helps understand combined parameter behavior.

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

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

The description states 'Search US export data by HS commodity code and/or country' with a specific verb, resource, and scope. This clearly distinguishes it from sibling tools like census_imports, census_trade_balance, and census_trade_trends.

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 clear parameter usage patterns: pass `country` as a plain English name, omit `hs_code` for country totals, omit `country` for all countries combined. However, it does not explicitly name alternatives like census_imports, though the tool name and context make the domain obvious.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds meaningful behavior: it returns 'import values, quantities, and commodity details,' and clarifies that country should be a plain English name. It does not cover pagination or limit defaults, but the output schema and schema descriptions fill those gaps. 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, front-loaded with the core purpose. The first sentence states exactly what the tool does; the second gives two critical usage examples. No fluff or redundancy.

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

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

Given the annotations, output schema, and well-documented parameters, the description covers the essential search patterns. It could have mentioned month/limit filtering or noted the availability of monthly data, but these are already in the schema. The description is complete for its role of guiding initial selection and invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining combined vs. separate usage of hs_code and country, and clarifies the meaning of omitting each parameter. It also reinforces that country is resolved to a code, which complements the schema's caution about country_code not being ISO. This goes beyond simple property descriptions.

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

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

The description clearly states the tool's function: 'Search US import data by HS commodity code and/or country.' It identifies the specific resource (US import data), the verb (search), and the key filters. It also distinguishes from sibling tools like census_exports by focusing on imports, and from census_trade_balance/trends by offering detail-level data.

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

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

The description gives clear context on how to use the tool and different modes: 'Omit hs_code for total imports from a country; omit country for all countries combined.' It also advises on passing 'country' as plain English. However, it does not explicitly name sibling alternatives or state when to prefer census_exports or census_trade_trends, so it stops short of full exclusion guidance.

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

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

Annotations already provide strong safety signals (readOnlyHint, idempotentHint, destructiveHint=false). The description adds useful context about the return value (breakdown by end-use commodity category) but does not disclose additional behavioral traits such as data limitations or filtering behavior. It is consistent with annotations, no contradiction.

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

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

The description is two sentences, front-loaded with the core action ('Check US trade balance'), then specifies output details. Every word is informative; there is no redundancy or fluff.

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

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

For a simple query tool with full schema coverage, an output schema, and detailed annotations, the description is complete enough. It states the core functionality and expected returns. It does not mention data source limitations or country-code alternatives, but these are covered by the schema and annotations, so the description does not need to repeat them.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds general context about using a 'specific country' and 'given year', but does not elaborate on parameter syntax, precedence, or formatting beyond what the schema already provides. It meets the baseline without adding significant extra semantic value.

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

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

The description uses a specific verb ('Check') and clearly identifies the resource (US trade balance for a country/year) and the output (net trade value and breakdown by end-use commodity category). This distinguishes it from sibling tools like census_exports and census_imports, which focus on individual flows rather than net balance.

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 states when to use the tool: to check US trade balance with a specific country for a given year. It does not explicitly name alternatives or exclusions (e.g., 'use census_exports for exports only'), but the context is clear enough for an agent to infer the appropriate use case.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds behavioral context beyond annotations by specifying the output granularity ('month-by-month values') and the analytical purpose ('identify seasonal patterns and shifts'). This usefully sets expectations 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?

Two sentences, front-loaded with the primary action ('Get monthly US trade trends'), and every word adds value. There is no repetition of schema details or fluff; the structure is efficient and clear.

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

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

With an output schema present, the description does not need to explain return values. It covers the tool's core purpose, scope (commodity/country), time dimension, and granularity. Minor omission is the lack of explicit mention of default date windows, but those are already in the schema, so the description is adequately complete for selection and invocation.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters (country, hs_code, end_year, start_year, country_code). The description adds no parameter-specific details beyond signaling that commodity and/or country are the main filters, which does not exceed the schema's existing descriptions. Baseline 3 applies.

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

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

The description uses a specific verb 'Get' and clearly identifies the resource: 'monthly US trade trends for a commodity and/or country over time.' This distinguishes it from siblings like census_exports, census_imports, and census_trade_balance by focusing on trends rather than categories or balance.

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 states the use case: 'Get monthly US trade trends... to identify seasonal patterns and shifts,' which implies when to use this tool (for time-series analysis). However, it does not explicitly name alternatives or state when not to use it, so it lacks the direct exclusionary guidance present in 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?

The description goes beyond annotations by detailing the data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), sorting by primary metric, return format (paired data + pipeworx:// URIs), and the fact it makes one parallel call. Annotations already indicate non-destructive, read-only, idempotent behavior, which is consistent.

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

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

The description is concise and well-structured, starting with example queries followed by details. Every sentence adds value; no fluff. It efficiently covers purpose, usage, data sources, and return format in a few sentences.

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

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

Despite no output schema, the description explains what is returned (paired data, citation URIs) and sorting behavior. It covers all aspects of the tool's operation. For a simple 2-param tool, this is complete.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds semantic context: for type, it specifies what data is pulled (revenue, net income, etc. for company; adverse events, trials for drug). For values, it gives examples and constraints. Slight improvement over schema.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs, with example queries like 'X vs Y' and 'rank these companies'. It distinguishes from sibling tools by explicitly saying it replaces 8-15 sequential lookups and should be preferred over 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?

The description provides explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It includes example query patterns. It does not explicitly state when not to use (e.g., if more than 5 entities needed), but the schema enforces limits. Overall, clear context for usage.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses decomposition/routing behavior, returns gaps[] and contradictions[], never-invented guarantee, semantic excerpting, timing expectations, and hop/citation_uri fields. No contradiction with annotations.

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

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

The description is long but every sentence earns its place: account prerequisites, core capability, sibling differentiation, depth semantics, return packet details, timing. It is front-loaded with the most critical operational constraint (account/sign-in) and organized logically.

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

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

For a complex tool with no output schema, the description fully explains the output: findings packet with verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], hop field, citation_uri. It also covers timeouts and iteration behavior, making it complete.

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

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

Although schema coverage is 100%, the description adds substantial meaning: it clarifies how 'question' can be broad and multi-part, explains the practical effect of depth levels (quick/standard/thorough) including paid plan and iteration/recovery behavior, which goes well beyond the enum 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 states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1412 STRUCTURED data sources... in ONE call.' It explicitly distinguishes itself from open-web search and from sibling ask_pipeworx for single lookups, making its purpose unmistakable.

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

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

Provides explicit when-to-use guidance: best for broad/multi-part questions over structured data, with examples; explicitly says use ask_pipeworx for single lookups and breaking news, and for users not signed in. Also covers paid-tier requirements for depth:'thorough'.

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 safety profile (read-only, idempotent, non-destructive). The description adds behavioral context: returns top-N tools with descriptions and schemas ready to call, no second lookup needed. This is valuable but could mention limitations like top-N default of 20.

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

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

The description is a single paragraph that front-loads purpose and usage. Each sentence adds value, though it could be slightly more concise (e.g., the list of domains could be abbreviated). 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 tool's discovery nature and lack of output schema, the description fully explains what it returns (top-N tools with names, descriptions, schemas) and when to use it. No gaps for its complexity level.

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

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

Schema coverage is 100% with descriptions for all parameters. The description complements by explaining query parameter usage with examples and noting aliases, adding practical guidance beyond schema descriptions.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the verb (find/discover) and resource (tools), and distinguishes itself from sibling tools (e.g., ask_pipeworx, census_exports) by being a meta-tool for discovery.

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

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

The description explicitly instructs when to use: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This contrasts with direct tool invocation, providing clear usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true. The description adds behavioral details: fans out across multiple sources, returns specific fields, patents API sunsetting will soft-fail, and it runs as a single parallel call. 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 long paragraph but front-loads usage examples. All sentences are relevant and informative, though it could be more structured (e.g., bullet points) for quicker scanning.

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

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

With no output schema, the description must explain return values. It comprehensively lists output fields: CIK, company name, recent filings with URIs, fundamentals, patents, news, LEI. It also notes limitations (patents sunset, name unsupported). Fully 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 good descriptions. The description reinforces that type must be 'company' and value must be ticker or zero-padded CIK, adding context about names not being supported and directing to resolve_entity. This adds value beyond the schema.

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

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

The description clearly states the tool returns a 'full cross-source profile of a US public company' in one parallel call, with example queries like 'tell me about X' and 'company profile for Microsoft'. It distinguishes itself from chaining single-pack SEC/XBRL/news 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?

Explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also advises using resolve_entity if only a name is available, as names are not supported.

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 destructive behavior; description adds context about clearing sensitive data, but does not mention idempotency or error handling on missing key.

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

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

Two sentences, front-loaded with action, then usage guidelines. No unnecessary words.

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

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

Adequately covers purpose, usage, and pairing. Lacks details on return values or error conditions, but acceptable for a simple delete 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 description doesn't add much beyond what the schema already provides for the single parameter.

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

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

The description clearly states the action is deleting a stored memory by key, differentiating it from sibling tools like 'remember' and 'recall'.

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

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

Explicit use cases are given: stale context, task completion, clearing sensitive data. Also pairs with remember and recall for 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?

Describes fetching the page, extracting title/description/key links, and emitting standard markdown. Annotations already indicate safe, idempotent read; description adds concrete steps 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?

Three sentences: purpose, process, use cases. No unnecessary words, each sentence adds value.

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

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

Despite no output schema, description clearly states output format ('single text blob ready to drop at site-root/llms.txt'). All relevant behavioral and usage info provided.

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

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

Schema covers both parameters fully. Description adds default (25) and max (50) for max_links, exceeding schema info.

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 'Generate a production-ready llms.txt file for any URL', specifies AI crawlers, and lists distinct use cases. Distinguishes from sibling tools like ai_visibility_check.

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: indexing a client's site, drafting for own project, auditing competitor. Does not explicitly state when not to use, but context is sufficient.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds return field details, confirming read-only behavior. No contradiction.

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

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

Two sentences: one for purpose, one for usage. No unnecessary words. Front-loaded with key information.

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

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

Simple tool with one optional parameter and no output schema. Description covers purpose, usage, and return fields adequately.

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

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

Schema provides full coverage for the single parameter `include_inactive` with description. The tool description adds no additional parameter info. Baseline 3 applies.

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

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

Clearly states verb+resource: 'List the caller's active subscriptions' and lists return fields. Distinguishes from siblings like subscribe/unsubscribe.

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

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

Provides explicit use cases: 'review what you're monitoring before adding more or to find an id to cancel'. Lacks explicit alternatives or when-not-to-use, but context is clear.

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

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

With all annotations set to false, the description fully carries the behavioral disclosure burden. It discloses rate limits ('Rate-limited to 5 per identifier per day'), quota impact ('Free; doesn't count against your tool-call quota'), and the human consequence ('The team reads digests daily and signal directly affects roadmap'). It also warns against pasting end-user prompts. 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 a single dense paragraph, but every sentence adds necessary context. It is front-loaded with the main purpose and then expands into guided usage, exclusions, and practical instructions. While it could be broken into bullets for scanability, it remains efficient and doesn't waste words.

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

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

For a straightforward feedback tool with a nested context object and no output schema, the description covers all essential aspects: purpose, when to use, exclusions, rate limits, quota, and content guidelines. It also explains the review cycle. There are no obvious gaps that would prevent an agent from correctly 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 value beyond the schema by explaining the enum categories in plain language ('bug = something broke...'), and it gives guidance on the context object ('Describe the issue in terms of Pipeworx tools/packs'), which helps the agent populate structured fields correctly. This pushes it above the 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?

The description opens with a clear verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It also distinguishes this tool from the sibling research tools by explicitly framing it as a feedback channel for Pipeworx-specific issues. This is specific and unambiguous.

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

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

Provides explicit when-to-use categories: '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 clear exclusions: 'if the tool came from a different MCP server... file it with that server instead' and offers a disambiguation rule about tool names. This is exemplary usage guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable context: caching intervals (5min-1h), no PII, and self-aggregating signal. 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?

Well-structured with bullet points and front-loaded key output. Slightly verbose but every sentence adds value. Could be trimmed slightly without loss.

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 only one optional parameter, no output schema, and rich annotations, the description covers purpose, usage, behavior, and caching. Sufficient for an agent to understand and invoke correctly.

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

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

Schema coverage is 100%. Description explains the window parameter's effect (shorter windows for hot topics, longer for steady-state) and provides default. Adds value beyond schema.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a recent window. It distinguishes itself from siblings by focusing on trend discovery, not querying or other actions.

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 tools, aligning use cases). Does not mention when not to use or alternatives, but the context is clear enough.

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

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

Beyond readOnly and idempotent annotations, the description discloses the semantic anchor (Jaccard similarity >= 0.30), partition filter (placeholder slug threshold), and fill check against CLOB depth. It explains that realizable_edge_pp ≤ 0 means no trade, adding critical 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 well-structured with sections and front-loaded purpose. While dense, every sentence adds value; minor verbosity does not hinder clarity. Could be slightly more concise but remains 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 covers response structure, including opportunities array fields, partition_check object, and fill_check details. Modes, filters, and edge cases are addressed, making it complete for complex arbitration detection.

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 event and topic parameters are explained with examples and behavior details beyond the schema. Description clarifies slug format, full URL acceptance, and how each mode processes markets, adding substantial value.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (trending_scan, event, topic) and contrasts with sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance: call with no args for trending scan, pass 'event' for per-event checks (recommended), or 'topic' for cross-event scanning. It explains when each mode is appropriate and references polymarket_fill_risk for alternative sizing 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 goes far beyond the annotations (which already declare readOnlyHint/idempotentHint/destructiveHint) by explaining internal model families, response structure (by_segment, diagnostics), caching (1h at KV level), and edge computation details (slippage, Kelly fractions). This provides a comprehensive understanding of the tool's behavior, outputs, and limitations.

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

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

The description is lengthy but well-structured with bold headings for model families and response segments. Every sentence adds necessary technical detail for a complex tool. However, it could be slightly more concise; some internal details (e.g., specific alpha values) might be considered excessive for a high-level description.

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

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

Given the tool's complexity, the lack of an output schema, and the thoroughness of the description, it covers all necessary aspects: purpose, models, response structure (including diagnostics), caching, parameter effects, and edge calculation. The description is complete enough for an agent to understand and 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?

The input schema already covers all 9 parameters with detailed descriptions (100% coverage). The description adds value by explaining the high-level purpose of 'tradeable-edge knobs' and their role in filtering, but it does not provide meaningful new information beyond what's in the schema. Per guidelines, with high schema coverage, baseline 3 is appropriate.

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

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

The description opens with a clear, specific statement: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It explicitly targets the use case 'what should I bet on today,' and details three distinct model families, making the tool's purpose unambiguous and well-differentiated from generic market tools.

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

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

The description provides extensive guidance on parameter usage (e.g., tradeable-edge knobs) and explains caching behavior, but it does not explicitly contrast this tool with its siblings (e.g., polymarket_arbitrage, polymarket_edge_tracker). There is no 'when to use vs. alternatives' statement, so the agent must infer use cases from the detailed functionality rather than receiving direct 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds behavioral details: it reads from daily snapshots, computes trend and decay, notes gaps when snapshots are missing, and explains that decay numbers come from daily closes not intraday. It also specifies history depth limited by a 60-day snapshot TTL. 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 well-structured with clear sections: purpose, args, response, limits. It front-loads the key idea ('Edge persistence and decay telemetry') and uses a direct quote to illustrate. Every sentence adds information without redundancy. It is comprehensive yet efficient.

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

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

Despite lacking an output schema, the description details the response structure (tracked[], expired[], snapshot_dates[]) and their fields, including edge_pp_net, trend, decay, lifespan_days. It covers input, output, and limitations (60-day TTL, gap handling, decay computation). This compensates fully for the missing 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 value by explaining the effect of parameters: e.g., 'days (lookback, default 14, max 30)' and 'window (snapshot family, default "1wk")' in the context of time-series and snapshot selection. While the schema already includes these details, the description reinforces their role.

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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question about edge longevity and decay, and distinguishes itself from sibling tools like polymarket_edges (which likely returns current edges only) by focusing on time-series analysis.

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

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

The description explains when to use this tool: to understand 'how long has this edge existed and is it shrinking?' and contrasts a fresh wide edge with a 3-week-old one. It does not explicitly list alternatives or when not to use, but the context implies it is for persistence analysis rather than real-time data. The mention of 'LIMITS' provides additional guidance on data bounds.

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 as read-only/idempotent; description adds critical context about partial basket fills creating unhedged directional risk and the impact of thin books. 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?

Well-structured with headers and bullets, but slightly verbose. Front-loads purpose, but some repetition could be trimmed.

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

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

Despite no output schema, description fully lists return fields for both modes, including verdict and edge cases like thin_legs and forced_directional_risk.

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

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

Schema coverage is 100%, but description adds meaning: explains side default logic in basket mode (auto), size_usd interpretation differences for buys vs sells, and mode selection. A bit more could be added but sufficient.

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

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

Clearly states the tool checks realizable vs theoretical edge against live order-book depth, distinguishes between single-market and basket modes, and contrasts with sibling tools by specifying when to use it before arb/edge signals.

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

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

Explicitly instructs to use this before executing arb signals or trades above ~$500, with reasoning about thin books and partial fills. No ambiguity.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description adds rich behavioral context: explains safety fields (compatibility_warning, temporal_alignment, skipped counters) and warns that spreads are rare. No contradiction with annotations.

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

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

The description is long but well-structured and front-loaded; every sentence adds value, though it could be slightly more concise without losing clarity.

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

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

Despite no output schema, the description thoroughly explains the response structure, safety fields, and interpretation, making it complete for a complex cross-venue analysis tool.

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

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

Schema coverage is 100% with descriptions; the description adds value by explaining the behavior of each parameter (topic values, explicit overrides) and providing examples, slightly exceeding the baseline of 3.

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

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

The description clearly defines the tool as cross-venue spread between Kalshi and Polymarket, differentiating it from siblings like polymarket_arbitrage by mentioning venue comparison and bet shape equivalence.

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 describes two modes (topic shortcuts for common macros, explicit tickers for custom pairs) and warns that most pre-mapped topics return compatibility warnings, thus 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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds further context about scoping and the dual behavior (retrieve vs. list), which is valuable beyond annotations. No contradictions.

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

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

The description is three sentences long, front-loaded with the action, and every sentence adds value. No extraneous 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 full schema coverage, annotations, and no output schema needed, the description provides all necessary context (purpose, usage, scoping, pairing).

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

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

Schema coverage is 100% for the single parameter 'key'. The description adds meaning by explaining that omitting the key lists all saved keys, which goes beyond the schema's description.

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

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

The description clearly states the verb ('retrieve' or 'list') and resource ('value previously saved' or 'saved keys'), and specifies the scope ('scoped to your identifier'). It also distinguishes itself from sibling tools like 'remember' and 'forget'.

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

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

The description explains when to use the tool ('look up context stored earlier... without re-deriving it from scratch') and mentions pairing with 'remember' and 'forget'. However, it does not explicitly state when not to use it or provide alternative tool comparisons.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds value by detailing return fields (source, citation_uri, raw payload) and the mark_read flag's effect on future calls. 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?

Five sentences, no filler. Front-loaded with action and resource, then covers returns, filtering, mark_read, and alternative access. 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?

With no output schema, description adequately describes return fields and behavior. Covers filtering, mark_read, polling suitability, and alternative access. 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?

Input schema has 100% description coverage. Description adds context beyond schema, e.g., explaining mark_read 'so the next call only shows newer ones' and providing an example type 'sec_8k'. Slightly above baseline 3.

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

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

The description clearly states the tool retrieves recent alerts from a subscription feed, using a specific verb ('Pull') and resource ('fired events from your subscription feed'). Distinguishes from sibling tools like list_subscriptions, which list subscriptions, not alerts.

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?

Mentions that polling is fine and provides an alternative API endpoint for scripts/dashboards, but does not explicitly address when to avoid this tool or compare to similar sibling tools. Provides guidance on mark_read and unread_only usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantive behavioral context: it fans out to three sources with fallback logic (GDELT preferred, GNews on rate limits/5xx), notes a soft-fail for USPTO due to API sunset, and describes the return structure (changes[] grouped by source + total_changes + citation URIs). This goes well beyond what annotations provide.

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

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

The description is front-loaded with typical user queries, then provides technical details. It is comprehensive but not overly verbose. Minor redundancy exists (e.g., '—' dashes could be more structured), but overall it efficiently conveys necessary information without wasting 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 tool's complexity (3 required params, multiple data sources with fallbacks, no output schema), the description is complete. It explains input formats, source behavior, return structure, and even includes a caveat about USPTO. The agent has all needed context to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining 'since' accepts both ISO dates and relative shorthand (with examples like '7d', '30d', '3m', '1y'), and clarifies that 'value' can be a ticker or zero-padded CIK. It also notes 'type' is limited to 'company' today. This supplements the schema descriptions usefully.

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

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

The description clearly states the tool provides a change feed for a company in a recent time window, listing multiple data sources (SEC, GDELT/GNews, USPTO) and explicitly distinguishes from the sibling tool 'entity_profile' which is for static profiles. The verb 'change feed' and resource 'company' are specific, and examples of typical queries make the purpose unmistakable.

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

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

The description gives explicit guidance on when to use this tool vs the alternative 'entity_profile': 'Use entity_profile instead when you want the static profile...'. It also illustrates typical use cases like 'What's new with X' and provides details on the 'since' parameter format (ISO or relative shorthand) to help the agent choose correctly.

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 idempotentHint=true and destructiveHint=false. The description adds valuable context about scoping by identifier and memory persistence (24 hours for anonymous, persistent for authenticated users).

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

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

The description is concise at 4 sentences, front-loaded with purpose, then usage, then technical details. No unnecessary words, though some might prefer even shorter phrasing.

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

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

For a simple key-value store with no output schema, the description covers purpose, usage, persistence, and tool pairings. No critical gaps identified.

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

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

Schema has 100% coverage with descriptions for both key and value. The description does not add new meaning beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool saves data for later reuse, and distinguishes itself from siblings recall and forget by explicitly mentioning 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 explicit when-to-use scenarios (discovering a resolved ticker, target address, etc.) and directs to recall/forget for retrieval/deletion.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and no destruction. The description adds behavioral context beyond annotations: it mentions internal cascading through multiple lookup endpoints, replaces 2-3 manual lookups, and describes the return values (including citation URIs). No contradictions with annotations.

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

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

The description is well-structured, starting with example queries to illustrate usage. It is slightly lengthy but each sentence adds necessary detail (supported types, return fields, internal behavior). No repetition or fluff.

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

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

Given the tool's complexity (2 required params, no output schema), the description adequately covers what the tool does, what inputs are accepted, what outputs are returned (including citation URIs), and internal behavior. It does not cover error handling or ambiguity resolution, but the annotations provide safety cues. Overall, it is complete for an AI agent's selection and invocation needs.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by providing concrete examples for each enum value (e.g., ticker AAPL, CIK 0000320193, drug names like ozempic). This helps the agent understand the expected input format beyond 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 specifies the tool's purpose: resolving a user-spoken name to a canonical identifier. It uses specific verbs ('resolve', 'look up') and identifies the resource (official identifiers for companies and drugs). The description distinguishes itself from siblings by explicitly stating to use this tool first when needing an ID, and it lists supported entity types with detailed return fields, making it distinct from other sibling tools like entity_profile or compare_entities.

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

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

The description provides clear usage context: 'Use FIRST whenever you have a name but need an ID.' It also implies when not to use (if you already have the ID) and explains that it replaces manual lookups. However, it does not explicitly list alternative tools or compare to siblings, which slightly reduces the score from a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds specific behavioral details: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density. No contradictions.

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

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

Two sentences, front-loaded with the core action, no unnecessary words. Every sentence adds value.

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

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

Given no output schema, the description adequately explains the return format (ranked list with score, confidence, signal density). Parameters are covered by schema, and the description clarifies the purpose and flow sufficiently.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds minor context (e.g., first entity treated as subject) but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the verb 'compare' and the resource 'AI visibility across multiple entities side-by-side'. It distinguishes itself from sibling tools like 'ai_visibility_check' by explicitly mentioning that it probes that tool and ranks results.

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 a concrete usage scenario ('competitive AI-marketing audits') and an example question. It implies the context for use but does not explicitly state when not to use this tool or mention direct alternatives beyond the underlying probe.

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

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

Discloses behavioral details beyond annotations: fans out across two services, partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed list on timeout. No contradiction with annotations (all readOnly, openWorld, 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 somewhat lengthy but front-loaded with the core purpose. Each sentence adds value, covering use cases, return details, and edge cases. Could be slightly more concise, but well-structured.

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

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

Given no output schema, the description thoroughly lists return fields (summary block, advisories, links, alternative versions) and explains partial failure behavior. It covers ecosystem scope and timing caveat, making it fully complete for agent use.

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

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

Schema coverage is 100% for both parameters. The description adds extra context: scoped packages accepted for 'package' and default to latest version for 'version', which adds meaningful semantic value beyond the schema.

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

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

The description clearly states the tool performs a composite check for adding npm packages, covering license, advisories, bundle size, etc. It uses specific verbs ('scan', 'fans out') and distinguishes itself from sibling tools by its unique functionality.

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

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

Explicitly tells when to use: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also specifies scope (NPM ecosystem only v1) and directs to alternative for other ecosystems via deps.dev:version directly.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint=false), the description adds critical behavioral details: uses BGE-base-en embeddings, cosine similarity on 500-char overlapping windows, 200K char cap with truncation flag, and returns character offsets and similarity scores. 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?

Five sentences, each earning its place. The first sentence front-loads the purpose, followed by usage guidance, technical details, and constraints. No filler or repetition.

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 compensates by explaining return values (passages, offsets, similarity scores). It covers constraints (character cap, truncation), embedding model, and pairing suggestion. Minor omissions: no explicit mention of whether multiple queries are supported or if text encoding is required.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds helpful query examples but mostly restates what the schema already provides for `text` and `limit`. It does not add substantial new semantic meaning beyond the schema.

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

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

The description uses a specific verb-resource combination ('semantic search inside a fetched record'), gives concrete examples (SEC 10-K body, article), and distinguishes itself from sibling tools like `ask_pipeworx_grounded`. It clearly communicates what the tool does and its niche.

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 using this tool when 'the record is too big to cram into the prompt' and mentions pairing with `ask_pipeworx_grounded`. While it doesn't explicitly list when not to use it, the context is clear enough for an agent to make appropriate decisions.

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

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

Discloses numerous behavioral traits beyond annotations: creation of persistent subscription, delivery channel constraints (email validation, phone verification needed, SMS 10/day cap, webhook auto-disable after 10 failures). 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?

Single paragraph is detailed and well-organized, but could benefit from bulleted structure for clarity. Front-loaded with main purpose, then elaborates on types and delivery.

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

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

Covers all necessary aspects: purpose, type parameters, delivery options, constraints, and return value (subscription ID). No output schema, but description sufficiently explains return. Complete for an agent to invoke correctly.

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

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

Adds significant value beyond the input schema: provides concrete examples for each type's params object (e.g., sec_8k items codes, fred_series series_id), explains delivery channel details (webhook HMAC signing, phone verification requirement). Schema coverage is 100%, but description enhances usability.

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 creates a proactive monitoring subscription to a live-data event stream and returns subscription ID. Lists multiple supported types with example parameters, distinguishing it clearly from sibling tools like 'list_subscriptions' or '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?

Provides context on when to use: requires Pipeworx OAuth account, anonymous/BYO cannot persist. However, no explicit comparison to alternatives or 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering safety and persistence. The description adds behavioral context about what the tool returns (category-bucketed example questions with exact tool+argument shape), which is meaningful beyond annotations. No mention of side effects or restrictions 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 appropriately sized for the tool's complexity. It front-loads the core purpose and example queries, then details output structure, and ends with usage guidance. Every sentence adds value with no redundancy or wasted words.

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

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

Given the tool's simplicity (1 optional param, no output schema, rich annotations), the description fully covers what the tool does, what it returns, and how to use it. There are no gaps in information needed for correct invocation.

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

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

Schema coverage is 100% with one optional 'topic' parameter described. The description repeats the parameter's effect ('pass `topic` to focus') but adds that omitting gives a cross-category spread, which is non-trivially derived from the schema. With full schema coverage, baseline 3 is appropriate.

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

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

The description clearly states it is an onboarding entry point for a new agent to discover Pipeworx capabilities. It lists example queries ('What can I ask Pipeworx?', 'show me examples') and describes the output (category-bucketed example questions with tool+argument shape). It distinguishes from siblings by advising 'Use this FIRST when you do not yet know what Pipeworx can do for you.'

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Provides clear invocation guidance: 'Call with no arguments for the full spread, or pass `topic` to focus.' No alternative tools are needed, so no exclusion necessary.

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

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

Annotations indicate destructiveHint=false and idempotentHint=true. The description adds valuable context: the row is deactivated (not deleted) and historical events remain available via recent_alerts. No contradiction with annotations.

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

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

Three sentences that are front-loaded and efficient. Every sentence provides essential information: action, ownership constraint, and side effect. No wasted words.

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

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

For a simple tool with one parameter and no output schema, the description covers operation, ownership, and side effects. It could mention whether cancellation is immediate or any additional effects, but it is mostly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions 'by id' but adds no additional meaning beyond the schema's description of the id parameter. No further detail on format or constraints.

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 'Cancel a subscription by id', specifying the verb and resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by mentioning ownership enforcement and deactivation behavior.

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

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

The description provides clear context by stating ownership enforcement ('you can only cancel your own subscriptions') and the deactivation behavior. However, it does not explicitly mention when not to use or compare with alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds significant behavioral context: it replaces 4-6 sequential calls, describes the two internal pipelines, and lists the verdict types and output structure (value with citation, reasoning). 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 relatively long but well-organized, starting with example queries and using a list for verdicts. Every sentence adds value, though some redundancy (e.g., restating the claim types) could be trimmed. Still, it efficiently conveys all necessary information.

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

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

Despite no output schema, the description fully explains the output structure (verdict, actual value with citation, reasoning). With only 2 parameters, both well-documented in schema and description, and rich annotations, the description leaves no critical gaps. The complexity of claim verification is well-addressed.

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

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

Schema coverage is 100% with good descriptions. The description adds value beyond schema: it explains that tolerance_pct overrides the implied tolerance, defaults to implied wording capped at 5, and clarifies how it affects grading (e.g., set 1-2 for hallucination detection). This helps the agent set parameters correctly.

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

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

The description starts with specific query examples and clearly states it validates natural-language claims against authoritative sources. It distinguishes two sub-paths (SEC EDGAR for financial claims, grounded pipeline for others), making its purpose unambiguous and differentiating it from sibling tools like deep_research or 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?

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It describes the routing logic for different claim types. While it doesn't explicitly list when NOT to use or provide concrete alternatives, the context is clear enough for an AI agent to decide appropriately.

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