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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the base behavioral profile is covered. The description adds meaningful context beyond annotations: it routes to 5,708 tools, returns structured answers with citation URIs, and mentions tiers ('works on every tier, one fast call'). It does not claim destructive side effects, consistent 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: it opens with the priority directive, enumerates domains, gives examples, and closes with routing to alternatives. Slightly verbose, but the density of useful guidance justifies the length.

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

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

The description is complete for a question-answering tool with one required param, no output schema, and rich annotations. It covers scope, alternatives, and expected output type. Minor gaps: it doesn't mention timeout/rate limits or how citation URIs are formatted, but nothing essential for invoking the tool is missing.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters, and they are all aliases for 'question'. The description provides example questions and clarifies that the parameter is a natural-language question, but it doesn't add much beyond the schema's own description. Baseline 3 applies because schema coverage is complete.

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 names a specific verb ('routes') and resource ('questions to 5,708 tools across 1,494 verified sources') and explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research. It also gives concrete examples of queries it handles, so an agent can clearly tell what this tool does and when it applies.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', gives trigger phrases ('what is', 'look up', 'find', 'get the latest'), and provides exclusion/step-up guidance: use ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions. This is strong when-to-use and when-not-to-use guidance.

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

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

Beyond the read-only and idempotent annotations, the description discloses crucial dynamic behavior: no candidate is currently active, so it matches ask_pipeworx exactly right now; candidates are enabled live under test; and it 'falls back to nothing' because it is a full working router. This is exactly the kind of context annotations cannot convey.

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

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

The description is front-loaded with the core purpose and the key facts are contained in four sentences. There is some redundancy around 'same arguments / same response shape / currently matches exactly' and the specific tool-count date is optional, but the content is meaningful and not padded.

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

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

The description explains current status, fallback behavior, and how the beta differs from the stable router. Since there is no output schema, the mention of 'same response shape' provides useful grounding, though it does not detail the actual response structure or what a routed result looks like.

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 documents all six parameters at 100% coverage: `question` and five aliases. The description only reuses 'same arguments' without adding any syntax, formatting, or usage semantics beyond the schema, so baseline 3 applies.

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

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

The description clearly identifies the tool as 'Beta version of ask_pipeworx' and explains it is an 'identical universal router' with the same 5,708 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx and the grounded variant by being the experimental routing edge, so an agent can tell them apart.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. It does not explicitly say when not to use it, but 'experimental edge' and the comparison against the stable router imply a stability trade-off.

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 that already mark read-only and idempotent, the description adds rich behavioral detail: exact success/refusal response shapes, the complete list of refusal_reason values, and the cost implication. It explains that the tool refuses rather than answers when data doesn't directly answer, which is critical for high-stakes use. No contradiction with annotations exists.

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 dense sentences but every clause earns its place: purpose, mechanics, output contract, use cases, and cost tradeoff. It is front-loaded with the core positioning, then flows logically into return values and refusal semantics. Despite the detail, it remains scannable and focused.

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

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

Given there is no output schema, the description responsibly specifies the full return contract including refusal reasons. It explains the shared routing with ask_pipeworx, names valid high-stakes use cases, and provides a cost-based alternative. An agent has what it needs to decide when to call and what to expect back.

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 schema already documents the question parameter and its aliases. The description doesn't add new parameter-specific detail—it focuses on tool-level behavior and output, which is appropriate but doesn't elevate parameter understanding.

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

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

The description opens with a precise concept: 'Hallucination-resistant answer mode for high-stakes reads.' It names a concrete behavior, 'EXTRACTS the answer using ONLY what the tool result contains,' and explicitly distinguishes it from its sibling ask_pipeworx. An agent can immediately tell when this tool differs from the other answer modes.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative and the tradeoff: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' No inference is needed to decide between the two tools.

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

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

Annotations 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 cover read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond those annotations: the performance constraint that an unfiltered monthly query spans every partner and cannot return in time, plus the month-by-month granularity. It does not contradict the annotations.

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

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

Two sentences carry all essential information with no filler. The primary scope, the required-country constraint, and the sibling alternatives are front-loaded and clearly stated.

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

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

For a tool with an output schema and a full input schema, the description covers the essential operational context: single-partner scope, optional HS narrowing, the performance reason for the country requirement, and the correct alternative for broader queries. Nothing important is missing.

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

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

Schema coverage is 100%, so the schema already documents all five parameters. The description reinforces the country requirement and explains the HS narrowing's purpose, but it does not add substantial per-parameter detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb+resource: it reports monthly US trade trends for one partner, with imports/exports and optional HS narrowing. It clearly distinguishes itself from census_imports/census_exports by stating the one-partner scope, so an agent can select it correctly without opening the schema.

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 explains when to use this tool: when analyzing a single trading partner, and warns that a country is required because an unfiltered query cannot complete. It also names the alternatives for all-countries totals: 'use census_imports / census_exports instead.' This is clear routing guidance.

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

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

The description 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 the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals many behavioral traits: account and paid-tier requirements, parallel tool routing, gaps[] for unanswered facets, no invented findings, hop field, resolvable citation_uri, contradictions[] for standard/thorough, semantic excerpting rather than head-truncation, and expected latency. This greatly exceeds what annotations alone communicate.

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 the tool is behaviorally complex and nearly every sentence carries actionable information. It is front-loaded with the account prerequisite and the most critical alternative, then flows from general behavior to depth options to output details and timing. It is dense but not padded.

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 compensates thoroughly by describing the findings packet, evidence fields, gaps[], contradictions[], citation behavior, hop field, and latency expectations. It also covers account constraints, alternative tools, and failure modes for out-of-catalog topics. An agent has enough context to call the tool correctly and interpret results.

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

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

Schema coverage is 100%, so the schema already describes both parameters well. The description still adds value by explaining that broad/multi-part questions are expected, giving example questions, and clarifying how the depth values behave in practice (gap recovery, chasing leads, contradiction pass). This goes beyond the schema without replacing it.

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

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

The description clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1494 STRUCTURED data sources' in one call, with a specific mechanism: decomposing questions into facets and routing them to 5,708 tools in parallel. It explicitly distinguishes itself from open-web search and from sibling tools like ask_pipeworx.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: best for broad/multi-part structured-data questions, use ask_pipeworx for single lookups and for breaking/current-news topics, and use ask_pipeworx if not signed in. It even names alternatives directly, leaving no ambiguity about tool selection.

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

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

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?

Annotations provide no safety hints (all false), so the description carries full behavioral burden. It fully discloses the claim_token flow, rate limit (5 per identifier per day), cost (free, no quota), and the fact that feedback is read daily. This goes well beyond annotations and sets clear expectations about side effects and follow-up behavior.

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?

Although the description is long, every sentence earns its place: purpose, usage criteria, exclusion, ambiguity resolution, parameter guidance, follow-up mechanics, impact, and limits. It is front-loaded with the core purpose and logically structured, making it easy for an agent to scan and extract key directives.

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 behavior for a complex feedback workflow: what to report, what not to report, how to phrase feedback, how to track a submission via claim_token, rate limits, and cost. No output schema exists, but the description explains return values (claim_token and later status). It is complete for both first-time and follow-up usage.

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

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

The input schema already covers all parameters thoroughly (100% coverage), so baseline is 3. However, the description adds valuable guidance for the message parameter ("Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt") and clarifies the claim_token usage pattern (pass it back with no other arguments). This elevates it above baseline.

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

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

The description opens with a specific verb and resource: "Tell the Pipeworx team something is broken, missing, or needs to exist." It clearly enumerates the feedback types (bug, feature, data_gap, praise) and distinguishes this tool from siblings like ask_pipeworx or discover_tools by focusing on reporting to the team rather than querying.

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 conditions: "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)." Also includes a clear exclusion: do not use for tools from other MCP servers, with guidance to file elsewhere. This is model behavior for usage guidelines.

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

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

Annotations already 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?

With readOnly, openWorld, and idempotent annotations already covering safety, the description goes well beyond by explaining pairing behavior, compatibility codes, skipped-leg accounting, temporal alignment, and the rule that unknown leg types are never paired. It even details a potential false-positive path: compatibility_codes can be non-empty even when matched_pairs>0. This is rich behavioral disclosure that no annotation could convey.

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

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

The description is long, but every section earns its place: purpose, two modes, response shape, safety fields, code definitions, skipped logic, and a closing caveat. It is front-loaded with the core definition and mode distinction before diving into response details. Some formatting like inline code and capitalization would improve scannability, but it is structured well for such a complex tool.

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

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

There is no output schema, so the description carries the full burden of explaining return values — and it does so thoroughly: leg prices, top_spreads_pp, compatibility warnings and codes, low-confidence pairs, temporal alignment, and skipped counters. It also preempts user confusion by noting that a returned pair still requires reading its compatibility flags. Given the tool's complexity and zero output schema, this is essentially 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?

The schema already documents all three parameters with 100% coverage, including the explicit override semantics, so the baseline is a 3. The description adds useful mode-level behavior: how topic maps to both venues, how explicit tickers override the mapped side, and how the absence of required parameters still yields meaningful output. That extra structural context raises it slightly above baseline.

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

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

The description opens with a specific, unambiguous statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This identifies a precise object and computation and clearly separates it from single-venue or arbitrage tools in the sibling list. The two modes are named explicitly, leaving no doubt about what the tool does.

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

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

The description gives clear selection guidance between its two modes: use `topic` for pre-mapped shortcuts and explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings. It also warns that most pre-mapped topics currently surface compatibility warnings and that 'pre-mapped ≠ tradeable,' which helps prevent misuse. It does not explicitly contrast this tool with sibling alternatives like polymarket_arbitrage beyond the inherent cross-venue framing, so it stops short of a 5.

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

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 state read-only, non-destructive, idempotent, and open-world hints, but the description adds significant behavioral context: every identifier is labeled with its source, unresolved identifiers appear under an 'unresolved' field rather than being silently omitted, LEI/FIGI enrichment degrades gracefully, and the tool internally cascades through several endpoints. 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 dense but every sentence contributes functional value: trigger examples, type resolution details, source attribution, error handling, and performance benefits. It is structured with a clear purpose statement up front, followed by type-specific details and caveats, making it easy to scan despite its length. The information-to-word ratio is high for the tool's complexity.

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

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

Given the tool's complexity (two entity types, multiple data sources, no output schema), the description covers all necessary aspects: input formats, resolved identifiers, source labeling, unresolved handling, fallback behavior (EDGAR still returns if GLEIF/OpenFIGI unavailable), and even internal cascading. This is more than complete for an AI agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% for both parameters, so baseline is 3, but the description substantially enriches the semantics: for 'company' it explains that input can be a ticker, CIK, ISIN, or company name, and details that an ISIN resolves to the legal entity via GLEIF mapping; for 'drug' it specifies the return fields (RxCUI, ingredient, brand). It also decouples the 'value' parameter from just a name, clarifying the range of accepted inputs.

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 an explicit verb-resource pair: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input,' immediately clarifying the tool's function. It also lists supported types ('company' and 'drug') and distinguishes itself from sibling tools by positioning itself as the first step for name-to-ID lookups, a unique role among the sibling tools.

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

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

The description gives concrete trigger examples ('What's the ticker for…', 'find the CIK for…') and an explicit directive: 'Use FIRST whenever you have a name but need an ID.' It also notes that the tool replaces 2-3 manual lookups, implying it should be preferred over alternative multi-step approaches, and clarifies unsupported cases by mentioning unresolved identifiers are explicitly reported.

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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses critical behavioral nuances: 'could_not_verify' means the check did not happen and must not be treated as evidence, carrying a verification_error object; 'unsupported' means no source coverage. It also clarifies the verdict types and the use of verbatim evidence with pipeworx:// citations. These details directly address potential misuse and are not present in the annotations or schema.

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

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

The description is front-loaded with trigger phrases and examples, making it immediately actionable. It is somewhat lengthy, but most sentences add value—covering routing, output contract, and error handling. However, it unnecessarily repeats tolerance details already present in the schema, which is a minor redundancy. Overall, it is well-structured for an AI agent, though not perfectly concise.

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

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

Given the tool's complexity and the absence of an output schema, the description provides a complete picture: it specifies the exact return fields (verdict, actual value with citation, reasoning), explains the distinction between 'could_not_verify' and 'unsupported', and describes the routing logic. This fully covers what an agent needs to invoke the tool and interpret results correctly, with no significant gaps.

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

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

Schema coverage is 100% for both parameters, and the schema already contains detailed descriptions for 'tolerance_pct' including its range, override semantics, and default cap. The tool description largely repeats this information (e.g., 'Overrides the tolerance implied by the claim wording' and 'Default: implied by wording, capped at 5') without adding new meaning. The 'claim' parameter is also adequately described in the schema with examples, so the description adds no significant extra parameter semantics.

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

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

The description explicitly states the tool performs natural-language claim verification against authoritative sources, with a clear verb-resource pair ('validate claim'). It distinguishes itself from sibling tools by describing a unified pipeline that handles both financial and general claims, and by specifying exact output verdicts. This makes the purpose unmistakable and unique among the sibling list.

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

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

The description provides explicit usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further differentiates use cases by routing company-financial claims through SEC EDGAR/XBRL fast path and all other claims through the grounded pipeline. It also notes that the tool replaces 4–6 sequential calls, giving clear context on when to invoke it over multi-step alternatives.

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