Airnow

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: scoring system, per-model response structure, and cost implications for Anthropic 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?

Six sentences, each serving a purpose. Front-loaded with main action and output, then details on models, return format, and use cases. No redundant 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?

With 4 parameters (1 required) and no output schema, the description explains return format (per-model fields + combined view) and covers key use cases. Provides enough context for correct 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 coverage is 100% with descriptions for all parameters. The description adds meaning about default model, which models require _apiKey, and that Anthropic calls are paid separately, enhancing understanding.

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

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

The description clearly states the verb 'probe', resource 'LLMs', and outputs 'visibility score (0-100) per model'. It distinguishes itself from siblings by focusing on brand visibility probing, unlike ask_pipeworx or deep_research.

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

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

The description lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It explains default model and when to provide _apiKey but does not explicitly state when not to use or compare to siblings.

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

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

Annotations already define this as readOnly/idempotent, and the description adds a significant layer: it Routes to 5,596 tools across 1,465 sources, fills arguments, and returns a structured answer with citation URIs. This makes the dispatching/auth behavior and the 'dispatcher' nature transparent, which is not visible from the annotations alone.

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 crucial instruction comes first ('PREFER...WEB SEARCH'), followed by domain list, routing behavior, and concrete examples—all useful. It stumbles slightly with some redundant boundary-case disclaimers near the end, but no sentence is wasted and it remains scannable.

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 readOnly, idempotent dispatcher with no output schema, this description covers what it takes, how it routes, what it returns, what credentials touch, and when to choose it. A precise output-contract description would be an improvement, but for an ask-and-route tool the coverage is solid.

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%: all six parameters are declared as aliases for the `question`/`q` parameter. The description provides useful example phrasings but not need to describe params further. Baseline 3 is appropriate when the schema already explains purpose; the examples only reinforce obvious...

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

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

Description opens with a direct, explicit instruction: 'PREFER OVER WEB SEARCH for questions about current or historical data' and follows with a concrete domain list and examples. It clearly distinguishes this tool as the broad, robust entry point for factual real-world questions, and routes around sibling search tools. Could not be mistaken for a generic 'ask' placeholder.

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

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

It explicitly says 'Use whenever the user asks...' with trigger phrases, includes 'even if web search could also answer it,' and flags the main alternative for live/monitor tasks. It also notes that breaking news is already covered. It would be stronger with detailed when-not-to-use clearly, but the guidance is ample and actionable.

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?

Given the readOnly, idempotent, non-destructive annotations, the description adds substantial context: it discloses that candidates may be actively tested, that none is currently active, that behavior currently matches ask_pipeworx exactly, and that it is a full router with no fallback. This is transparent and useful.

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

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

The description is front-loaded with the essential beta identity and communication status. Some sentences are slightly redundant, reapeating the identical/stable equivalence, but it remains compact and readable.

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

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

For a routing tool with no output schema, the description gives the key missing context: why it is beta, how it compares with ask_pipeworx, what the current runtime state is, and what 'beta' does not mean. It still relies partially on the ask_pipeworx definition for a full behavioral model, but it is coherent and adequate for 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 all aliases already documented. The description just says the same arguments as ask_pipeworx, which is sufficient and does not need to restate 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 positions this as the beta version of the ask_pipeworx universal router, idticount to ask_pipeworx in tools, arguments, and response shape. It distinguishes it from the stable sibling via the experimental routing edge. However, it still relies on ask_pipeworx being understood to fully convey what the actual answer-generation behavior is.

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 says explicitly to use it exactly like ask_pipeworx when you want the newest routing, and it explains the comparison against the stable router. The beta-vs-stable distinction is clear, though it stops short of an explicit 'use ask_pipeworx instead when...' rule.

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

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

Annotations already indicate read-only and idempotent behavior, but the description adds crucial behavioral detail: it may return explicit refusals with classified refusal_reason values, and the output includes verbatim evidence. It also reveals the cost tradeoff (one extra LLM call), which is valuable context beyond annotations.

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

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

The description is long but each part serves a clear purpose: it defines the mode, explains behavior, lists return and refusal shapes, and gives use-case guidance. It is somewhat verbose with exact counts and reasons, but remains tightly organized and front-loaded with the core differentiator.

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, the description covers intent, routing, output contract, refusal cases, and usage trade-offs. There is no output schema, so this description carries the full burden, and it does so thoroughly. Nothing needed to invoke it correctly 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%: all six parameters are aliases for 'question' and are fully described in the schema. The description does not add parameter-specific information, but none is needed; baseline 3 applies.

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

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

The description states a precise purpose: a grounded, hallucination-resistant answer mode that extracts answers only from tool results. It explicitly contrasts itself with the sibling ask_pipeworx and clarifies its special role, so an agent can distinguish it from the 36 siblings.

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

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

The description gives explicit use-or-not guidance: use when the answer will be quoted/cited/acted on and hallucination must be avoided, and prefer ask_pipeworx for casual lookups. This is an actionable, context-rich alternative.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description significantly adds value by detailing the resolution process, classification, parallel fan-out, response shapes, safety blocks, cancellation rules, and handling of illiquid markets, with no contradictions to 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 verbose with multiple sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). While structured and informative, it could be more concise without losing critical details. The length may still be acceptable for a complex tool, but it does not achieve maximum conciseness.

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

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

Given the tool's complexity (3 parameters, no output schema), the description covers all necessary aspects: usage, behavior, response structure, edge cases, safety, resolution risks, and field explanations. It is highly complete and leaves little ambiguity for an AI agent.

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

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

Schema coverage is 100% with clear descriptions for all three parameters. The description enhances understanding by explaining the market parameter accepts slug, URL, or question text; depth affects evidence count; and include_raw controls payload size. This goes beyond the schema, justifying a score 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 explicitly states the tool researches a Polymarket bet by pulling Pipeworx data in one call, with a specific verb, resource, and scope. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by offering a comprehensive one-call research, making its purpose unique and clear.

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

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

The description provides explicit usage scenarios such as 'should I bet on X', 'what does the data say about Y', and 'is there edge in Z'. It also discusses blocking conditions (low-confidence matches, closed markets) but does not directly contrast with sibling tools, missing an opportunity to clarify when to use alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable behavioral context: data sources (10-K, FAERS), handling of fiscal years, and citation URIs. 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 packed with useful information but is somewhat long. However, every sentence adds value, and the structure with examples and specifics is effective. A bit verbose but not wasteful.

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

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

Given the complexity (two entity types, multiple data sources, sorting, citations), the description covers all necessary aspects. Explains return format despite no output schema. 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 is 100%. The description adds meaning beyond the schema by explaining that 'values' expects tickers/CIKs for company and drug names for drug, and reinforces min/max constraints. Provides clarity on usage.

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: side-by-side comparison of 2-5 companies or drugs in one parallel call. It lists common query phrasings and distinguishes from sequential single-pack lookups, making the purpose unambiguous.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and describes when to use company vs drug type. Lacks explicit exclusion for more than 5 entities, but otherwise provides strong guidance.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds 'latest observed' and 'nearest station' but does not disclose edge cases like missing stations or single-result limitation. With annotations present, the description provides adequate but not extra 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?

A single clear sentence with no redundancy. Every word adds value and the purpose is immediately understood.

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, the presence of annotations, a complete input schema, and an output schema, the description is sufficiently complete. It succinctly describes the core function without needing further detail.

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 all parameters are documented in the schema. The description does not add additional semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

Description clearly states the tool returns the latest AQI for the nearest AirNow station given lat/lon coordinates. This differentiates it from the sibling tool 'current_by_zip' which uses a ZIP code.

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

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

The description implies usage when latitude and longitude are available, but does not explicitly state when to use this tool over alternatives like 'current_by_zip' or mention any exclusions. Guidance is minimal but not misleading.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds behavioral specifics: returns one record per pollutant, uses nearest site, includes category and timestamp. This context goes beyond the annotations without contradicting them.

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 convey the core purpose, return structure, and typical behavior. No extraneous content; front-loaded with the primary action. Highly efficient.

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

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

Given the output schema exists (context signal) and annotations provide safety profile, the description is complete for a simple read tool. It explains what data is returned and the geographical resolution (nearest site). No obvious 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?

The input schema covers 100% of parameters with descriptions for zip_code and distance_miles. The description does not add new parameter information, so it relies on the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns the latest observed AQI for a US ZIP code, specifying it returns one record per pollutant (typically O3 and PM2.5) with AQI value, category, area, and timestamp. This distinguishes it from sibling tools like current_by_location (which uses lat/lng) and forecast_by_zip (forecast).

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 implicitly defines usage: querying current AQI by ZIP. However, it does not explicitly state when to use this tool versus alternatives like current_by_location or forecast_by_zip, nor does it mention exclusions (e.g., non-US ZIPs). Sibling tools are listed in context but not referenced in the description.

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 readOnly, openWorld, idempotent, and non-destructive behavior, so the description's job is to add context. It does: account/paid-plan gating, parallel decomposition into facets, verbatim evidence with confidence/source/citation, explicit gaps[], never-invented behavior, contradictions at standard level, semantic excerpting, and time expectations. No contradiction with annotations exists.

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

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

The description is long and dense, with nested parentheses, but it is front-loaded with the most critical operational constraints: account requirement and the alternative tool. Every substantial chunk adds distinct information, and the structure reasonably flows from gating to behavior to outputs, though it could have been trimmed for readability.

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

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

Given the tool is complex, has only 2 params, no output schema, and no annotation for return shape, this description is unusually complete: it covers outputs, citation fetchability, multi-hop depth behavior, timing, error gaps, and how to choose an alternative. An agent has enough context to invoke it 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?

Since schema coverage is 100%, the baseline is 3. The description adds question-phrasing examples and clarifies 'thorough' requires a paid plan, but the deep semantics of depth already appear in the enum. It doesn't materially expand the meaning of either parameter beyond what the schema provides.

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

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

The description states a specific verb and resource: 'Grounded multi-source research' across 1465 STRUCTURED data sources, and explicitly adds what it is not — 'this is NOT open-web search.' It gives concrete example questions ('compare X and Y's regulatory + financial exposure') and distinguishes itself from ask_pipeworx, making sibling differentiation clear.

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

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

Usage guidance is explicit and actionable. It says 'Best for broad/multi-part questions over structured data', 'If you are not signed in, use ask_pipeworx instead', and 'For a single lookup use ask_pipeworx'. It also explains depth values and associated behaviors. This leaves little 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?

Discloses that results include schemas and are ready to call directly; annotations already indicate read-only and idempotent behavior. No contradictions, but could add more about limits or side effects.

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

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

Description is structured with front-loaded purpose, each sentence adds value, though slightly long for a search-like tool.

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

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

Given 6 parameters and no output schema, description adequately covers return format and usage context, with examples and note on direct callability.

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 aliases and examples already documented; description adds usage examples but does not provide new meaning beyond what schema offers.

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

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

The description clearly states 'Find tools by describing the data or task' and lists specific domains, differentiating from siblings by advising to call this FIRST when exploring the option set.

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 ('Use when you need to browse...') and advises 'Call this FIRST', but does not explicitly state when not to use or name alternative tools, though 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 indicate readOnly, openWorld, idempotent, non-destructive. Description adds significant behavioral context: fans out across multiple sources, returns specific fields (CIK, filings, fundamentals, patents, news, LEI), mentions soft-fail for patents, and notes one parallel call. 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 a single dense paragraph but is front-loaded with example queries. Every sentence adds value, but it could be slightly more structured (e.g., bullet points for return fields) without losing information. Still, it is efficient and not overly verbose.

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 comprehensively lists return fields (CIK, company_name, recent_filings, fundamentals, patents, news, LEI) with sufficient detail (e.g., URIs, sort order, potential soft-fail). It also explains input constraints and usage context. Minor gaps like error handling are acceptable for a profile tool.

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

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

Schema coverage is 100% with both parameters described. Description adds value by reinforcing that 'value' can be ticker or zero-padded CIK, names are not supported, and providing format details (e.g., '0000320193'). It also clarifies the 'type' enum is currently limited to 'company'.

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

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

Description starts with diverse example queries, then states the tool's purpose clearly: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from sibling tools like resolve_entity and compare_entities by highlighting its holistic, multi-source approach.

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

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

Explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also explicitly states when not to use: 'Names not supported (use resolve_entity first if you only have a name).' Provides clear context and 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 comprehensive behavioral hints (readOnly, openWorld, idempotent, non-destructive). The description adds no additional behavioral context beyond what is in the annotations. This is adequate but not extra.

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 primary action, and contains no unnecessary words. It efficiently conveys the tool's purpose and a typical use case.

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

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

Given that an output schema exists, the description does not need to explain return values. It covers the main purpose and date default but does not mention the distance_miles parameter. Still, the tool is relatively simple and the schema handles remaining details.

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 input schema already documents all parameters. The description only restates the date default, adding no new semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly defines the tool as providing an AQI forecast for a US ZIP code on a given date, with a default to today. It uses a specific verb (forecast) and resource (AQI), and distinguishes from sibling tools like current_by_zip by focusing on future predictions.

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

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

The description explicitly states a use case ('is tomorrow ok for outdoor activity'), implying when this forecast tool is appropriate. While it does not explicitly contrast with current conditions tools, the context is clear enough for the agent to differentiate from siblings.

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

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

Annotations already indicate destructiveHint=true, and the description confirms the delete behavior. It adds context about clearing stale/sensitive data, but the core transparency is already covered by annotations.

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

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

Two concise sentences with no wasted words. Front-loaded with the action, followed by usage guidance. Every sentence adds value.

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

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

For a simple delete tool with one parameter and no output schema, the description fully covers purpose, usage, and behavioral context. No gaps remain.

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

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

Schema coverage is 100% with a clear parameter description. The description does not add additional meaning beyond the schema, so 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 'Delete a previously stored memory by key', specifying the verb, resource, and means. It distinguishes from siblings by mentioning '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?

Explicitly provides when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with 'remember' and 'recall', aiding 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 indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds the process (fetches page, extracts title/description/links) and output format (single text blob for site-root/llms.txt), which complements the annotations without contradicting them.

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 plus a usage note, with no redundant information. It is front-loaded with the core purpose and succinctly covers all essential aspects.

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 tool is simple with two parameters and no output schema. The description explains the output format and use cases fully. Given the annotations and schema richness, no further details are needed.

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

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

Schema coverage is 100% with clear descriptions for both parameters (url and max_links). The description does not add substantial new meaning beyond what the schema provides, so a 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 generates a production-ready llms.txt file for any URL, specifying the verb (generate), resource (llms.txt), and purpose (AI crawler indexing). It distinguishes from sibling tools like ai_visibility_check and scan_competitor_ai_presence by focusing on output generation rather than 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 provides explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitor visibility. It does not explicitly list when not to use or alternatives, but the context is clear enough for an agent to decide.

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 and idempotent hints. The description adds value by listing return fields and implying default filtering of active subscriptions, but behavioral traits are well-covered by annotations.

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

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

The description is two sentences, front-loaded with purpose, and every sentence provides useful information without redundancy.

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

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

For a simple list tool with one optional parameter and sibling tools, the description is complete. It specifies return fields and usage context, sufficient for an agent to use correctly.

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

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

Schema coverage is 100%, so the parameter's description in the schema already explains include_inactive. The tool description mentions 'active' which hints at the default, but no additional meaning 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 the tool lists the caller's active subscriptions and specifies return fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

The description provides guidance on when to use the tool: to review subscriptions before adding more or to find an id to cancel. It does not explicitly mention when not to use, but the context is clear.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds minimal behavioral context beyond the annotations, such as the bbox format and pollutant specification. It does not discuss pagination, rate limits, or data sparsity.

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

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

The description is two sentences long, front-loaded with the primary purpose, and contains no superfluous information. Every sentence earns its place.

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

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

Given full schema coverage, annotations, and an output schema, the description covers the essential usage context. It could mention time granularity (hourly) or that results may include multiple sites, but the output schema likely clarifies this.

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

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

Schema coverage is 100%, and the schema includes descriptions for all parameters. The description adds an example of pollutant codes but does not provide additional meaning beyond what the schema already conveys.

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 it returns 'Historical AQI observations inside a bounding box for a date range,' which is a specific verb+resource combination. It clearly distinguishes itself from sibling tools that focus on current or forecast data, such as current_by_location or forecast_by_zip.

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

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

The description implies usage for historical AQI queries but does not explicitly state when to use this tool versus alternatives like current_by_location. There is no mention of caveats, limitations, or contraindications.

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 are all false hints, so the description carries the full burden of behavioral disclosure. It clearly explains side effects and workflow: filing without an account returns a claim_token, how to use it later to check resolution, daily digest review, rate limiting (5 per identifier per day), and that it's free with no quota count. It also clarifies the non-destructive nature by describing it as feedback submission. No contradiction with annotations; the description adds substantial behavioral context beyond the structured fields.

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

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

The description is long but every sentence delivers new information: what it does, when to use it, when not to use it, how to phrase feedback, the claim_token flow, team response time, and rate limits. It is purposefully organized, front-loaded with the core purpose, and contains no redundancy or filler. Each sentence earns its place, making it an efficient, well-structured description despite its length.

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

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

Given the tool's complexity (multiple feedback types, claim_token follow-up, scope restrictions) and the absence of an output schema, the description still covers all necessary aspects: return value (claim_token), how to use it, rate limits, scope boundaries, and actionable guidance. It is complete for an agent to correctly select and invoke this tool, including making appropriate decisions about whether to use it at all.

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 meaningful semantic enrichment: it tells users to 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which clarifies the message parameter's expected content. It also explains the claim_token parameter's follow-up flow ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') beyond the schema's brief description. This justifies a score 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 clear, specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates the exact kinds of feedback (bug, feature/data_gap, praise) and distinguishes itself from siblings like ask_pipeworx by focusing on reporting issues about Pipeworx tools rather than querying. This fully differentiates the tool from all 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?

Provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and tells the user to file elsewhere if the tool came from another MCP server. It even offers a test for ambiguity: 'Pipeworx tool names are the ones this connection lists.' This is exemplary usage guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, not destructive. Description adds: data source (CF analytics-engine), no PII, caching (5min-1h), and return format. This provides comprehensive 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?

Description is well-structured with bullet points. Every sentence is informative, no fluff. Appropriately sized for the tool's simplicity.

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

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

Given no output schema, the description explains return values (top tools, top packs, volume). Also covers data source, privacy, caching, and parameter details. Complete for a read-only trending 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 covers the single parameter (window) with enum and description. Description adds semantic guidance: shorter windows for hotness, longer for steady-state. This adds value beyond the schema.

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

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

The description clearly states the tool returns top tools, top packs, and call volume over a window. It distinguishes from sibling tools like ask_pipeworx or discover_tools by focusing on trending/aggregated 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?

Three explicit use cases are provided (discovering hot data sources, confirming canonical choice, aligning use case). No explicit when-not-to-use, but the context is clear enough to avoid misuse.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), description adds critical behavioral details: fill check with realizable_edge_pp ≤ 0 signal to not trade, semantic anchor for similarity, partition filter for placeholders, and response structure.

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?

Very informative but somewhat dense; could be slightly more streamlined. However, it is front-loaded with the main purpose and modes, and each section 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, the description fully explains return values (opportunities[], partition_check, fill check results) and trade implications. Covers edge cases like low similarity and placeholder filtering.

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 significant extra meaning: provides example values for event slugs and topics, explains URL acceptance, and describes mode-specific behavior for each 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 tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no-args trending scan, event mode, topic mode) and explains each, differentiating from sibling tools.

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

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

Explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also directs to polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context, including the three model segments, response structure with edge_pp_net and Kelly fractions, 24h-move warnings, caching behavior, and diagnostic counters, all 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 verbose, containing deep technical details about model formulas and internal logic. While well-structured with front-loaded purpose, it is not concise and could overwhelm an AI agent seeking quick understanding.

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

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

Given the complexity (9 parameters, no output schema, many siblings), the description is highly complete. It explains the response structure, caching, diagnostics, and tradeable-edge knobs in detail, compensating for the lack of an output schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by explaining tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) and differentiating min_kelly vs min_partition_leg_kelly, which goes beyond the schema descriptions.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It distinguishes itself from siblings by focusing on 'what should I bet on today' and avoiding paging through markets, which differentiates it from tools like polymarket_arbitrage.

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

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

The description indicates the tool is built for discovering opportunities without paging through markets, providing implicit usage context. However, it does not explicitly compare with sibling tools or state when not to use this tool, which limits the 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 adds significant detail beyond annotations: explains the trend and decay computation, the structure of response fields (tracked, expired, snapshot_dates), and limitations (60-day TTL, daily closes, not intraday). Annotations only indicate read-only, non-destructive, idempotent, open-world, so description enriches understanding.

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

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

The description is comprehensive yet each sentence adds value. It front-loads the core purpose, then details response structure, and ends with limitations. No filler 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?

With no output schema, the description thoroughly explains the response: tracked[], expired[], snapshot_dates[], including field meanings and edge_pp_net interpretation. It also covers history bounds and data source. This makes the tool fully self-contained.

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 repeats parameter info (lookback, clamp, default) but adds no new semantics beyond what 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 clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from siblings like polymarket_edges by focusing on time-series, not just current edges.

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

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

The description implies usage for evaluating edge freshness versus age, contrasting 'fresh wide edge' with '3-week-old wide edge'. While it does not explicitly name alternative tools, the context from siblings and the tool's name makes the use case 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 declare read-only, open-world, idempotent, non-destructive. The description adds behavioral context: it simulates fills, walks ladder, returns verdict. It warns about thin books and partial fills, which goes beyond 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 detailed but well-organized with headings for each mode. It front-loads the purpose. While somewhat verbose, every sentence adds value and there's 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?

Despite no output schema, the description fully explains return fields (top_of_book, VWAP, slippage, verdict, etc.) and covers edge cases like thin legs and forced directional risk. It addresses the dominant loss mode in arb bots.

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 the description adds value by explaining size_usd differently for single-market (spend/proceeds) vs basket (settlement notional), side defaults, and market vs event requirement. This goes beyond the schema's 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 it performs a realizable-vs-theoretical edge check against live order book depth, distinguishing single-market and basket modes. It uses specific verbs like 'check' and 'walks the ladder', and contrasts with sibling tools polymarket_arbitrage and polymarket_edges.

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 tool before acting on arb signals or trades above $500. It explains why (partial fills convert arb to unhedged directional position) and distinguishes from alternative tools, leaving 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?

Annotations confirm read-only, idempotent, non-destructive behavior. The description adds extensive behavioral details: two modes, response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and conditions for meaningful spreads. 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 long but every sentence provides essential information. It is front-loaded with the core purpose and then details modes, response, and safety fields. A bullet list could improve readability, but it is not excessively verbose.

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

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

Given the tool's complexity (multiple modes, safety checks, temporal alignment) and lack of output schema, the description is remarkably complete. It covers response fields, warning conditions, and explains why most shortcuts are not tradeable, leaving little ambiguity.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by explaining the modes and how topic maps to venues, and clarifies that explicit parameters override topic mappings. This goes beyond the schema, justifying a 4.

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

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

The description clearly states it is a cross-venue spread between Kalshi and Polymarket, with two modes (topic shortcuts and explicit tickers). This differentiates it from sibling tools like polymarket_arbitrage (intra-venue) and polymarket_edges.

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 topic mode vs explicit mode, and warns that most topic shortcuts return compatibility warnings, setting realistic expectations. However, it does not explicitly mention when not to use the tool or compare with alternatives, though the context is strong.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds value by explaining the retrieval operation, scoping, and pairing intent, without contradicting annotations.

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

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

Three sentences, no fluff. Core function first, then usage context, then scoping. Every sentence contributes meaning.

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 one optional parameter, no output schema, and rich annotations, the description covers all necessary context: two usage modes, scoping, and tool pairing. Nothing 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 fully covers the optional parameter with a clear description. Description adds contextual examples (ticker, address, notes) that help the agent understand typical usage 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?

Description clearly states it retrieves a value by key or lists all keys when omitted, using specific verbs and resource. Differentiates from siblings 'remember' and 'forget' by naming them and describing their roles.

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

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

Explicitly says 'use to look up context the agent stored earlier' and notes scoping to an identifier. Mentions pairing with remember/forget, but lacks explicit when-not or alternatives beyond sibling names.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds behavioral details: mark_read flags events read, polling works, and the direct endpoint alternative. 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 that front-load the core purpose. Could be slightly tighter but no unnecessary words. Well-structured with key details upfront.

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

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

Given no output schema, the description explains return fields (source, citation_uri, raw payload) and provides context for polling vs direct endpoint. Covers all important aspects for a read-only poll tool.

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

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

Schema coverage is 100%. Description adds meaning beyond schema: explains mark_read effect ('flag returned events read so the next call only shows newer ones'), clarifies filters (type, since). Adds value to 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 specifies exactly what the tool does: 'Pull fired events from your subscription feed' and lists key return fields. It clearly distinguishes from sibling tools like 'list_subscriptions' or 'recent_changes' by focusing on subscription feed 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?

Provides guidance on filtering (type, since) and the mark_read flag behavior. Mentions polling works fine and an alternative direct endpoint for scripts/dashboards. Lacks explicit when-not-to-use but overall helpful.

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

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

Annotations already provide readOnlyHint, idempotentHint, and openWorldHint. The description goes beyond by detailing internal behavior: fan-out to multiple sources (SEC, GDELT→GNews fallback, USPTO), handling of rate limits and soft-fails, and return structure with citation URIs. No contradictions with annotations.

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

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

The description is fairly concise but could be slightly tighter. It efficiently front-loads with example queries and uses parentheticals for fallback behavior. Every clause serves a purpose, though some redundancy (e.g., listing the same fallback in two ways) 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?

Given the tool's complexity (multiple sources, fallback, no output schema), the description covers key aspects: sources queried, return structure (changes grouped by source, total_changes, URIs), and parameter behavior. However, it lacks explicit details on the fields within each change object or pagination, which could be inferred from context but not stated outright.

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?

Despite 100% schema description coverage, the description adds significant value: it explains the 'type' enum's current limitation ('Only "company" supported today.'), provides concrete examples for 'value' (ticker or CIK), and elaborates on 'since' with format details ('ISO date...or relative shorthand') and a recommended default. This goes well beyond the schema definitions.

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

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

The description provides example queries that clearly illustrate the tool's purpose, specifies it is a change feed for companies, and distinguishes it from the sibling tool 'entity_profile', which is explicitly mentioned as the alternative for static profiles.

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

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

The description explicitly states when to use this tool ('What's new with X' queries) versus alternatives ('Use entity_profile instead when you want the static profile'). It also provides guidance on the 'since' parameter with suggested values ('Use "30d" or "1m" for typical monitoring').

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 idempotentHint=true and destructiveHint=false. The description adds critical behavioral detail: persistent vs. 24-hour retention based on authentication, key-value pair structure, and scoping. No contradiction with annotations; description adds significant value beyond structured fields.

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, focused paragraph of 4 sentences, efficient and front-loaded with the core action. Could be slightly more structured (e.g., using bullet points for retention rules), but it is compact and informative.

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 (write-only, 2 params, no output schema) and presence of annotations, the description covers key behavioral context (retention, scoping, pairing). The only minor gap is not mentioning success/failure indicators, but for a write tool this is acceptable.

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

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

Input schema covers both parameters with descriptions (100% coverage). The description gives naming conventions and examples ('subject_property', 'target_ticker') but does not add essential semantic constraints beyond schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for later reuse, uses a specific verb ('Save'), and distinguishes from sibling tools like recall and forget. It provides concrete examples (resolved ticker, target address, user preference) that make the purpose unambiguous.

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

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

The description explicitly advises when to use ('when you discover something worth carrying forward') and mentions alternatives (recall, forget). It also notes scope (scoped by identifier) and retention differences by authentication. Lacks explicit 'when not to use' guidance, but the positive usage context is strong.

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

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

The description adds significant behavioral context beyond the annotations. It explains cascading internal lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, output format with source labels and explicit unresolved list, and the citation link for drug lookups. The annotations already declare readOnly, idempotent, and non-destructive, and the description enriches this with operational details without contradiction.

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

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

The description is well-structured and front-loaded with purpose and usage guidance. It uses bullet-like formatting for supported types and details. However, it is somewhat verbose, with multiple sentences detailing edge cases and output formats. While every sentence adds value, a slightly more terse version could achieve the same clarity. Overall, it earns its length but is not maximally 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 (two parameters, no output schema, fallback behaviors), the description is exceptionally complete. It covers input formats, output structure, source labelling, graceful degradation, and even provides a citation pattern. The absence of an output schema is fully compensated by the detailed description of returned identifiers. No gaps remain for an agent to correctly invoke the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining the output identifiers for each type (CIK, ticker, LEI, FIGI for company; RxCUI, ingredient, brand for drug) and input flexibility (ticker, CIK, ISIN, name). It also clarifies fallback behavior and the purpose of each parameter in context. This goes beyond the schema's enum and type 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 resolves names to canonical identifiers, with specific verb 'resolve' and resource 'entity'. It lists example queries and distinguishes itself from sibling tools implicitly by being the designated name-to-ID lookup tool. The supported types (company, drug) are explicitly defined, and the description uses concrete language like 'resolve a user-spoken NAME to the canonical/official identifiers'.

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

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

The description provides explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also gives examples of appropriate queries. However, it does not specify when NOT to use this tool nor mention alternatives (e.g., entity_profile, compare_entities). The context is clear and sufficient for most cases, but the lack of exclusions keeps it from a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, indicating safety and non-destructiveness. The description adds valuable detail: it internally calls ai_visibility_check for each entity, returns a ranked list with score, confidence, and signal density. No contradictions found.

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-loading the purpose and benefits immediately. Every sentence adds value: the first says what it does and how, the second gives a concrete use case and describes the output. 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 no output schema, the description adequately explains the return format (ranked list with score, confidence, signal density). It also describes the internal mechanism (probes with ai_visibility_check). However, it does not elaborate on error cases (e.g., missing API key for anthropic) or timeouts, but that's acceptable for a comparative tool.

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

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

Schema coverage is 100% with descriptions for all four parameters. The description adds context beyond the schema: it clarifies that entities should be 2-8, the first is the subject, and explains the models and _apiKey options. This adds meaning for correct usage.

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 compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces which entity is most/least recognized. The verb 'compare' and resource 'AI visibility' are specific, and it differentiates from sibling tools like ai_visibility_check (single entity) and compare_entities (different purpose).

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

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

The description provides a concrete use case for competitive AI-marketing audits and an explicit question motivating the tool. It implies when to use (side-by-side comparison over single visibility checks), but does not explicitly state when not to use or mention alternatives like compare_entities. Still, the guidance is clear.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable behavioral context: partial failures, response structure (summary block, per-advisory detail, links, alternative versions), and timing caveat (bundlephobia first measurement 5-30s). No contradictions.

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

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

Description is fairly long but well-structured: starts with purpose, then usage, response components, ecosystem scope, and fallback. Every sentence is informative. Minor room for trimming but overall efficient.

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

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

Given the tool's complexity (multiple data sources, partial failures, no output schema), the description fully covers what the agent needs: inputs, outputs, failure modes, and scope. It is complete and actionable.

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%. Description adds practical details: clarifies scoped packages accepted and default version behavior (latest when omitted). This goes beyond the schema's descriptions, earning 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?

Description clearly states it's a composite check for 'should I add this npm package' combining deps.dev and bundlephobia. The verb 'scan_dependency' and resource 'dependency' are specific, and it distinguishes from unrelated sibling tools (e.g., scan_competitor_ai_presence).

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

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

Explicitly says 'Use whenever an agent asks...' and provides concrete queries. Also notes NPM-only scope in v1 and mentions fallback for other ecosystems via deps.dev directly. Provides clear when-to-use and when-not.

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

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

Annotations already indicate readonly, open-world, idempotent, non-destructive. The description adds crucial behavioral details beyond annotations: embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character limit (200K chars truncated and flagged), and the purpose of offsets (allowing agent to verify verbatim quotes). This is excellent transparency.

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

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

Single paragraph with a logical flow: purpose statement, usage scenario, output description, pairing hint, and technical details. Every sentence earns its place; no redundant phrasing. Concise yet comprehensive.

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 (passages with character offsets and similarity scores). Covers technical constraints (model, window size, character limit) and pairing with a sibling. The tool is fully described for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces the text parameter with a clear explanation and size limit, gives example queries for the query parameter, and implicitly defines limit through schema. Adds some value but does not significantly surpass schema detail.

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 'Semantic search INSIDE a fetched record' and gives concrete examples (SEC 10-K, article, tool result). It specifies the output (top-N passages with offsets and similarity scores). The name 'search_within' is well differentiated from siblings like 'ask_pipeworx_grounded' which is explicitly mentioned as a complement.

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

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

Explicitly advises using when the record is too large for the prompt, saving context. Mentions pairing with ask_pipeworx_grounded. Does not explicitly list when NOT to use or alternative sibling tools, but the guidance is clear enough for typical agent 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 indicate mutable, open-world, idempotent, non-destructive behavior. The description confirms creation and authentication needs but adds no major behavioral context beyond what annotations provide, such as side effects or rate limits for the creation itself.

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 and front-loaded, with each section adding value. It is slightly verbose but efficient given the complexity. Every sentence serves a purpose.

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

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

Despite no output schema, the description covers subscription types, parameters, delivery options, authentication, and limitations comprehensively. It adequately prepares an agent to use the tool correctly.

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

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

Schema coverage is 100%, and the description adds extensive meaning with examples for each type and delivery channel, including type-specific filters, delivery constraints (e.g., phone verification, daily SMS cap), and webhook details. This significantly aids parameter understanding.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns a new subscription ID. It specifies subscription types and distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

The description explains when to use (proactive monitoring) and prerequisites (Pipeworx OAuth account, no anonymous/BYO). It provides context on delivery limitations but does not explicitly contrast with alternative tools or state when not to use.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: returns category-bucketed example questions with exact tool+argument shape, and explains topic filtering. This is meaningful beyond the annotations.

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

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

The description is slightly long but extremely information-dense, front-loading the purpose and usage. Every sentence serves a purpose, and the structure is logical.

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 role as an onboarding entry point with one optional parameter and no output schema, the description covers everything needed: output format, usage scenarios, and how it fits with sibling tools.

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

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

Schema coverage is 100% with one optional parameter. The description explains the topic parameter with examples and default behavior (full spread), adding significant 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 it is the onboarding entry point for an agent that just connected, returning category-bucketed example questions. It distinguishes itself from sibling tools by being the first tool to use when the agent is unfamiliar with Pipeworx's capabilities.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides guidance on using with or without the topic argument. Mentions alternatives like ask_pipeworx, entity_profile, compare_entities as meta-tools.

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

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

Adds value beyond annotations: explains ownership enforcement, deactivation (not deletion), and impact on historical events. 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, no wasted words, action front-loaded. 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?

For a simple 1-param tool with no output schema, the description fully covers ownership, behavior, and lifecycle implications.

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 the lone parameter completely (100% coverage). Description adds minimal but useful context ('by id'). Baseline 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') and resource, distinguishing it from siblings like 'subscribe' and 'list_subscriptions'.

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?

Gives explicit context: ownership enforcement and deactivation behavior. Does not explicitly state alternatives or when not to use, but the context is sufficient.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description discloses critical behavioral nuances: 'could_not_verify means the check did not happen ... NOT evidence for or against the claim' and 'unsupported means we looked and cover no source for it'. It also describes the two pipelines (SEC EDGAR/XBRL fast path vs grounded pipeline), which is essential for interpreting results. 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 longer than typical but every sentence adds value. It is front-loaded with trigger phrases and a clear use case. The structure flows from user intent to implementation details to return semantics. It could be slightly tightened, but the length is justified by the complex verification behavior and 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?

Given the tool's complexity (two routing paths, multiple verdict categories, error semantics) and the lack of an output schema, the description covers everything an agent needs: verdict values, evidence format, error conditions ('could_not_verify' vs 'unsupported'), and performance benefit. It fully compensates for the missing output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical semantic depth beyond the schema by illustrating how tolerance_pct should be used ('set 1–2 for hallucination detection where any material error must be refuted') and providing natural-language claim examples in the schema. This goes beyond the schema's basic description of parameters.

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

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

The description clearly states a specific verb+resource: natural-language claim verification against authoritative sources, with explicit example phrasings. It distinguishes itself from sibling Q&A/research tools by focusing on fact-checking claims and returning a verdict, and it explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.'

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 the agent needs to check whether something a user said is factually correct') and also clarifies the internal routing logic for company-financial vs other claims. It contrasts with the alternative of 4–6 sequential calls by saying 'Replaces 4–6 sequential calls', making the tool's advantage clear.

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