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, and idempotentHint, and the description does not contradict them. It adds useful behavioral context beyond the annotations: the tool routes to one of 5,798 tools across 1,517 sources, fills arguments automatically, and returns answers with stable pipeworx:// citation URIs, and is described as a single fast call.

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

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

The description is long but well-structured and front-loaded: the first sentence gives the primary use case, the middle gives trigger phrases and examples, and the later sentences are short exclusivity rules that route to siblings. Every sentence carries actionable information with very little fluff for the amount of guidance packed in.

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 one-required-parameter, read-only, idempotent tool with no output schema, the description covers the essential invocation context: what kinds of questions it answers, what the response includes, and how it relates to a wide set of sibling tools. The return value is described sufficiently even though there is no output schema.

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

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

Schema coverage is 100% with clear alias descriptions for all six parameters, so the baseline is 3. The description adds value by giving concrete natural-language query patterns and examples such as 'current US unemployment rate' and 'Apple's latest 10-K', which clarify what kind of input belongs in the question field beyond the schema's generic 'Your question or request in natural language.'

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 'PREFER OVER WEB SEARCH' and clearly names the resource: current/historical factual data across SEC, FDA, FRED/BLS, patents, real estate, news, stocks, and more. It states the precise action: routes the question to the right tool and returns a structured answer with stable pipeworx:// citation URIs, distinguishing it from web search and 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?

It gives explicit when-to-use triggers ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), concrete examples, and explicit when-not-to-use alternatives: ask_pipeworx_beta for product questions, ask_pipeworx_grounded for accountability-sensitive answers, subscribe for alerts, compare_entities for decision matrices, and deep_research for multi-leg workflows. This is exactly the level of routing guidance an agent needs.

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

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

Discloses beyond annotations that this is an experimental edge with candidate routing improvements enabled live and that no candidate is currently active, so it currently matches ask_pipeworx. Also states it has no fallback and is a full working router, which is useful operational context. No contradiction with annotations.

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

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

Four sentences, each carrying distinct information: identity, current candidate state, usage, and fallback behavior. Front-loaded with the core beta definition.

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

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

Complete enough for an experimental variant of a known sibling: it explains current behavior, how to invoke it, and the comparison process. It omits no critical operational detail, and response shape is covered by 'same response shape' reference.

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 documents all six parameters and states question accepts q, prompt, text, and input as aliases, so coverage is 100%. Description mentions 'same arguments' but adds no parameter-level detail; schema carries the burden.

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?

States it is the beta version of ask_pipeworx, a universal router with the same 5,798 tools, arguments, and response shape, which is specific and differentiates it from the stable sibling. The verb 'ask' plus 'router' conveys the function clearly.

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

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

Explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and notes results are compared to the stable router to decide merges. It implies the stable alternative for non-experimental use, but does not spell out a when-not condition or mention ask_pipeworx_grounded.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavior beyond that: the refusal contract with five enumerated refusal_reason values, the guaranteed verbatim evidence quote, the grounding constraint ('using ONLY what the tool result contains'), the extra LLM call cost, and the scale of the routing (5,798 tools across 1,517 sources). This is rich, non-redundant behavioral disclosure with 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?

Every sentence earns its place: purpose is front-loaded, then mechanism, then the success return shape, then the refusal contract, then usage guidance, then the cost tradeoff. The description is longer than average but the tool is genuinely complex with two return modes and an explicit refusal path — the density is justified and there is zero filler.

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

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

With no output schema, the description carries the full burden of explaining return values — and it does, covering both the success shape (answer, evidence, confidence, source, fetched_at) and the refusal shape with all possible refusal_reason enum values. Combined with annotations covering safety, the cost tradeoff, and explicit usage boundaries, an agent has everything needed to decide whether to call this tool and what to expect back. Nothing material 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 fully documents the 'question' parameter and its aliases. The description adds meaning beyond the schema by explaining what happens to the question: it is routed to the right tool across thousands of sources, has arguments filled, and the fetched data is used for grounded extraction. This tells the agent the parameter's processing pipeline, which the schema alone does not convey. Slightly above the 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 states a specific verb+resource: a 'hallucination-resistant answer mode' that 'EXTRACTS the answer using ONLY what the tool result contains.' It clearly distinguishes itself from ask_pipeworx by name ('Same routing as ask_pipeworx') while specifying the grounded behavior that makes it different. An agent can tell exactly what this tool does and how it differs from its closest sibling.

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' with concrete domains (financial verdicts, legal claims, medical lookups, public statements). It also gives an explicit when-not-to-use with the alternative named: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' Nothing is left to inference.

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?

Annotations already mark the tool read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond that: account/paywall requirements, parallel decomposition across 5,798 tools, the findings-packet structure with gaps[], contradictions[] behavior, citation_uri fetchability, semantic excerpting, and latency expectations. There is no contradiction with the annotations.

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

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

The description is long but information-dense, and the most decision-critical facts are front-loaded: account requirement and fallback tool first, then use cases. It is structured as one continuous block rather than scannable sections, and a few caveats are repeated, but nearly every sentence contributes distinct value for a tool with no output schema.

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 everything needed to select and correctly invoke this tool: authentication constraints, alternatives, ideal use cases, counter-indications, parameter semantics, return packet contents, citation resolution, gap handling, contradiction detection, and expected latency. Given the tool's complexity and lack of an output schema, this is highly 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 for parameters is 100%, but the description goes well beyond the schema by explaining the depth enum's behavioral meaning: quick=3 facets, standard adds gap recovery plus contradictions[], thorough is paid and chases leads. It also clarifies that question accepts natural-language multi-part research questions, which is exactly the semantic context an agent needs.

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

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

The description states a clear verb-resource pair: grounded multi-source research across Pipeworx's 1517 structured data sources in one call. It also explicitly distinguishes itself from open-web search and from the ask_pipeworx sibling, so an agent can tell them apart immediately.

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: best for broad/multi-part questions over structured data, and for single lookups or breaking/current-news topics it directs the agent to ask_pipeworx instead. It even names the alternative for unsigned-in users, 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?

The annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, but the description adds substantial context: parallel fan-out across nine sources, soft-failure of the USPTO feed after May 2025, 'an empty section is a real no data, not a bug,' and 'resolved:false with an explicit notes line' for private companies. This goes well beyond the structured annotations and sets accurate expectations for both success and failure modes.

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 and dense, especially the single run-on sentence listing all return sections, but almost every clause carries operational information. It is front-loaded with the core purpose and routing preference, and the detailed caveats are all useful given the tool's complexity and lack of an output schema. It could be better structured, but it contains no filler.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: cik, company_name, resolved_from/to, recent_filings with URIs, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, sources_used, and sources_failed. It also explains edge cases like private companies, expected empty sections, and source soft-failures, so an agent has enough context to invoke the tool and interpret its response correctly.

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

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

Schema coverage is 100%, so the schema documents both parameters well. The description adds genuine value by clarifying that `type` accepts 'company' or 'ticker' interchangeably, that `value` can be a ticker, CIK, or name regardless of `type`, and that names resolve via SEC EDGAR's company-name match. This normalization semantics is the kind of nuance an agent needs 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 states a specific action and resource: 'full cross-source profile of a US public company in ONE parallel call,' reinforced by concrete user phrasings like 'Tell me about X' and 'company profile for Microsoft.' It distinguishes itself from sibling tools by saying it fans out across SEC, XBRL, patents, contracts, FDA, hiring, news, and GLEIF, so an agent can clearly tell entity_profile apart from single-source lookups like resolve_entity or compare_entities.

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

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

It gives an explicit routing rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies accepted value shapes (ticker, zero-padded CIK, or company name) and the expected behavior for private companies (resolved:false with notes), leaving no ambiguity about when and how to invoke the tool.

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

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

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

The annotations mark the tool read-only and idempotent, and the description adds extensive operational disclosure: pairing is keyword-based and unverified, spreads are gross not net of Kalshi fees, unknown legs are never paired, and null temporal_alignment means uncomputable rather than aligned. This goes well beyond the annotation baseline.

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 it is well-structured with labeled sections and each caveat addresses a real interpretation risk. It could be tightened in places, but the density is largely justified for a tool with this many edge cases.

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 semantics. It covers leg-by-leg prices, top spreads, per-entry flags, compatibility codes, fee treatment, skipped-leg counters, and temporal alignment semantics. Nothing essential for correct invocation and interpretation is missing.

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

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

The input schema already gives 100% parameter coverage with examples, but the description adds meaning about the two modes, override behavior, and that both modes run the same matcher. This adds real value beyond the schema's field 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?

States a specific verb and resource: measuring the cross-venue spread between Kalshi and Polymarket for the same resolving question. It also differentiates from sibling tools by centering on cross-venue comparison and matched outcomes, with compatibility warnings defining the tool's scope.

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?

Clearly explains two invocation modes (topic shortcuts vs explicit ticker/slug) and that both run the identical matcher. Provides practical guidance like reading warnings even when matched_pairs>0 and warns that pre-mapped topics are not necessarily tradeable, though it does not explicitly name sibling alternatives.

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

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

Annotations already provide readOnlyHint=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?

The description discloses extensive behavior beyond the readOnly/idempotent annotations: ambiguous matches return figi_candidates rather than asserting, unresolved identifiers are explicitly listed, enrichment degrades gracefully, and ISINs resolve to legal entities via GLEIF. This gives the agent a strong model of what the tool does internally and how it handles edge cases.

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

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

The description is dense but well organized, front-loading purpose and usage before dropping into supported types and caveats. It earns most of its length, though a few details are repeated or could be tightened without losing value.

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

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

For a complex tool with no output schema, the description is remarkably complete: it covers supported types, input formats, output identifiers, ambiguity handling, unresolved fields, and graceful degradation. An agent has enough context to call it correctly and interpret results in nearly all cases.

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

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

Although schema coverage is 100%, the description adds crucial meaning, especially for 'value': it instructs agents to pass the entity name only, shows examples, and warns against trailing security-class words for bonds. This goes well beyond the schema's terse descriptions.

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

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

The description states a specific action—resolving a user-spoken name to canonical/official identifiers—and supports it with concrete query examples. It also distinguishes itself as the first step when an ID is needed, separating it from siblings like entity_profile or validate_claim.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID,' and enumerates supported entity types and acceptable input forms. It does not explicitly name sibling tools as alternatives or state when not to use this tool, so it stops short of a full 5.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description provides a concrete usage scenario ('competitive AI-marketing audits') and an example question. It implies the context for use but does not explicitly state when not to use this tool or mention direct alternatives beyond the underlying probe.

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

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

Discloses behavioral details beyond annotations: fans out across two services, partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed list on timeout. No contradiction with annotations (all readOnly, openWorld, idempotent, non-destructive).

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

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

The description is somewhat lengthy but front-loaded with the core purpose. Each sentence adds value, covering use cases, return details, and edge cases. Could be slightly more concise, but well-structured.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

With no output schema, the description compensates by explaining return values (passages, offsets, similarity scores). It covers constraints (character cap, truncation), embedding model, and pairing suggestion. Minor omissions: no explicit mention of whether multiple queries are supported or if text encoding is required.

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

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

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

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

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

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

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

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

The description explicitly advises using this tool when 'the record is too big to cram into the prompt' and mentions pairing with `ask_pipeworx_grounded`. While it doesn't explicitly list when not to use it, the context is clear enough for an agent to make appropriate decisions.

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

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

Discloses numerous behavioral traits beyond annotations: creation of persistent subscription, delivery channel constraints (email validation, phone verification needed, SMS 10/day cap, webhook auto-disable after 10 failures). No contradiction with annotations.

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

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

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

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

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

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

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

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

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

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

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

Clearly states it creates a proactive monitoring subscription to a live-data event stream and returns subscription ID. Lists multiple supported types with example parameters, distinguishing it clearly from sibling tools like 'list_subscriptions' or 'unsubscribe'.

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

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

Provides context on when to use: requires Pipeworx OAuth account, anonymous/BYO cannot persist. However, no explicit comparison to alternatives or when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering safety and persistence. The description adds behavioral context about what the tool returns (category-bucketed example questions with exact tool+argument shape), which is meaningful beyond annotations. No mention of side effects or restrictions beyond annotations.

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

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

The description is appropriately sized for the tool's complexity. It front-loads the core purpose and example queries, then details output structure, and ends with usage guidance. Every sentence adds value with no redundancy or wasted words.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description clearly states 'Cancel a subscription by id', specifying the verb and resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by mentioning ownership enforcement and deactivation behavior.

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

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

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

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

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

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.