Nws

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

Discloses default model, cost implications (BYO key for Anthropic), and return structure (per-model score, confidence, signals, raw_response). Adds value beyond annotations which already indicate read-only, idempotent, non-destructive behavior.

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

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

Two concise sentences with front-loaded action. Every sentence adds essential information; no redundancy or fluff.

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

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

Given no output schema, the description effectively explains the return shape (per-model + combined view) and use cases. Could include a note about the 'combined view' format, but overall sufficient.

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

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

Schema coverage is 100% with descriptions. The description further explains that 'models' defaults to workers-ai, _apiKey enables Anthropic probing, and context helps disambiguation, enriching 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 explicitly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100). It distinguishes itself from siblings like ask_pipeworx and deep_research by focusing on AI visibility audits.

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 clear use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use the _apiKey parameter. Lacks explicit contrast with similar tools but offers good context.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds useful context: it routes to thousands of tools, fills arguments, returns structured answers with stable citations, and is fast ('one fast call'). No contradictions with annotations, and the added detail enriches the safety profile without repeating it.

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 front-loaded with the key directive 'PREFER OVER WEB SEARCH'. It effectively uses examples and explicit alternatives. Some slight redundancy ('START HERE... default entry point' and 'works on every tier, one fast call') but overall every sentence earns its place for a tool with this scope.

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

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

Despite no output schema, the description explains the return format (structured answer with stable pipeworx:// citation URIs), covers a wide range of use cases from SEC filings to weather, and clearly situates the tool among siblings. It is complete for a general-purpose lookup 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 description coverage is 100%—the 'question' parameter is well-documented, including aliases. The tool description adds examples of valid questions, which is helpful, but it doesn't provide additional parameter semantics beyond what the schema already states. Baseline 3 applies.

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

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

The description clearly states the tool routes questions to one of 5,529 tools across verified sources, fills arguments, and returns structured answers with citation URIs. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point for factual questions.

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

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

Explicitly says to prefer this over web search, lists trigger phrases like 'what is' and 'look up', provides concrete examples, and gives clear guidance on when to use alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions). Also notes it handles breaking news, so no need for a separate news tool.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description adds context: 'identical universal router... same 5,529 tools, same arguments, same response shape' and 'falls back to nothing — this IS a full working router'. This is useful beyond annotations, though it doesn't disclose rate limits, persistence, or response format (but response shape is stated as identical). 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 four sentences, each earning its place: what it is, what's different, current state, when to use it. It is front-loaded with the beta status and contains no redundant 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?

Given the 6-parameter schema with 100% coverage and no output schema, the description adds the key operational context: identical to ask_pipeworx, live experimental routing, and current status. It could mention whether results include experimental flags or how to compare against stable, but the description is complete enough for a full working router.

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

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

The schema covers 100% of parameters, with the 'question' parameter well-described and five aliases listed. The description adds no extra semantics beyond calling it a 'universal router' and referencing 'same arguments', but the schema already provides full coverage, 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 this is the beta version of ask_pipeworx with identical routing and an experimental edge, and it differentiates it from ask_pipeworx by mentioning 'candidate routing improvements' and 'experimental edge' — while noting it currently matches ask_pipeworx exactly. It could more explicitly tie it to the 'ask a question' verb, but the context and sibling names make the purpose evident.

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 it exactly like ask_pipeworx when you want the newest routing' and explains the comparison-to-stable-router context. It doesn't enumerate when not to use it or contrast it with all siblings (e.g., ask_pipeworx_grounded), but it gives a clear directive for when to prefer it over the stable variant.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial behavioral context: it extracts answers only from tool results, returns a structured refusal on insufficient data, lists specific refusal reasons, and quantifies the extra cost. This goes beyond the annotations.

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

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

The description is long but information-dense and front-loaded with the key distinguishing value. Sentences are structured to cover purpose, behavior, refusal semantics, and usage guidance. A slight cut could make it punchier, but no sentence is wasted.

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 having no output schema, the description fully documents the return shape, including the success fields and all refusal reason values. This covers the behavioral contract needed for an agent to invoke and interpret results correctly, making the description self-sufficient.

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

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

Schema description coverage is 100%, and the schema itself documents the 'question' parameter and its aliases. The description mentions accepting a natural language question but adds no extra semantic detail beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode' for high-stakes reads, with a specific verb and resource. It explicitly distinguishes itself from the sibling ask_pipeworx by noting the routing is the same but the output includes evidence and explicit refusals.

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: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also provides a clear alternative: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost.

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

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

Goes far beyond annotations by detailing resolver contract (matching confidence, alternatives), parent_event extraction, news fallback, safety short-circuits, liquidity warnings, and cancellation rule parsing. No contradiction with readOnlyHint or other 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?

Long but well-structured with clear sections (classifiers, fan-out examples, response shapes, safety). Front-loads core purpose. Could be slightly more concise, but the density is justified by tool complexity.

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

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

No output schema exists, but the description fully compensates by detailing response structure (result.market, result.analysis, result.evidence) and covering edge cases (closed markets, low-confidence matches, wide spreads, cancellation rules). Remarkably complete for a complex tool.

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

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

Schema coverage is 100% and the description adds meaningful context for all three parameters (market input types, depth defaults, include_raw recommendation). Also includes examples that clarify 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 explicitly states it researches a Polymarket bet by pulling Pipeworx data, specifies input types (slug, URL, question text), and distinguishes from sibling tools with clear use cases like 'should I bet on X'.

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

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

Provides explicit when-to-use scenarios ('Use for...') and detailed fan-out examples, but does not explicitly state when not to use or name alternative sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

The description discloses behavioral traits beyond annotations: it details the data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and output format (paired data + citation URIs). No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint).

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 average but every sentence adds value, with examples front-loaded. It could be slightly tighter but is well-structured 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?

Despite no output schema, the description fully explains the return format (paired data + citation URIs) and covers all important behaviors for a tool with 2 parameters. It is complete for its complexity.

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

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

Schema coverage is 100% and both parameters are described. The description adds meaning by explaining the effect of each enum value for type (company vs drug) and the expected input format for values (tickers vs drug names), significantly enriching beyond the schema.

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

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

The description uses specific verbs like 'compare' and clearly states the resources (companies, drugs) and scope (2-5 entities). It distinguishes itself from sibling tools by explicitly stating it should be preferred over sequential lookups.

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

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

The description provides explicit query patterns (e.g., 'X vs Y', 'which is bigger') and instructs to always prefer this tool over sequential single-pack lookups, giving clear when-to-use guidance.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive; the description adds substantial behavioral context: account/paid-tier requirements, parallel decomposition across 5,529 tools, findings packet structure, gaps[] to avoid inventing, contradictions[] scanning, semantic excerpting, and timing. Also discloses that breaking-news topics return mostly empty gaps[].

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

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

The description is dense and information-rich but long (~300 words). It front-loads the critical account requirement and then the core purpose. Some redundancy exists (repeated emphasis on structured data and 'never invented'), but every sentence carries functional value for a complex tool.

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

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

For a tool with no output schema, it thoroughly explains the return packet: verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, citation_uri. It also covers failure modes (empty gaps), timing, and account restrictions, making it one of the most complete descriptions possible.

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 100% of params with detailed depth enum description. The description adds context: question is 'Broad/multi-part is fine — decomposition is the point', and depth levels map to hop behavior and paid status. It reinforces but goes a little 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?

Purpose is highly specific: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call. It explicitly differentiates from siblings by stating 'this is NOT open-web search' and contrasts with ask_pipeworx for single lookups and breaking news. Verbs like 'Decomposes... routes... returns' make the mechanism 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?

Provides explicit when-to-use: 'Best for broad/multi-part questions over structured data' with concrete examples. Explicitly names alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING... prefer ask_pipeworx'. Also notes account prerequisites and fallback if not signed in.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds that it returns top-N ready-to-call tools with schemas, providing extra context. 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?

Single paragraph with clear front-loading of purpose and usage. Contains some redundancy (multiple synonyms for search) but still reasonably 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?

Covers purpose, usage, return value, and examples. Lacks details on default limit or error handling, but sufficient for a discovery tool with good annotations.

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

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

Schema coverage is 100%, so baseline is 3. Description reiterates aliases and gives examples but adds minimal new parameter-specific info beyond what schema provides.

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

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

Clearly states the tool is for finding tools by describing data/task, lists specific data domains, and distinguishes itself as a first-call discovery tool for browsing available options.

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 when you need to browse...' and 'Call this FIRST when you have many tools available'. Does not explicitly state when not to use, but context implies it's for discovery before selecting a specific tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Beyond that, the description details the fan-out behavior across sources, specific returned fields, patent API sunset with soft-fail, and that names are not supported. 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 verbose (~150 words) but packs in numerous details and examples. It front-loads with example queries. While not perfectly concise, every sentence adds value, making the length acceptable.

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

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

Despite no output schema, the description thoroughly explains what is returned (cik, company_name, recent_filings with URIs, fundamentals, patents status, news fallback, LEI). It also notes the patent API sunset and fallback behavior, covering behavioral nuances comprehensively.

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 significant value: examples ('AAPL', '0000320193'), clarification that value must be ticker or zero-padded CIK, and that type is currently only 'company'. This goes well beyond the schema's minimal descriptions.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call'. It explicitly lists the data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and outputs, distinguishing it from chaining single-pack lookups.

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

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

The description provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies constraints: 'names not supported (use resolve_entity first if you only have a name)' and gives example inputs.

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, so description reinforces the destructive nature. It adds valuable context on why deletion is appropriate (stale data, sensitive data), which aids agent in selecting the tool appropriately.

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, no unnecessary words. It is front-loaded with the primary purpose and immediately provides usage context and related tools.

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 operation with one parameter and no output schema, the description covers purpose, usage guidelines, and relationships. No gaps are evident given the tool's simplicity.

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 single parameter 'key' described as 'Memory key to delete'. The description does not add additional semantic meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Delete' and the resource 'memory by key'. It distinguishes itself from sibling tools 'remember' and 'recall' by explicitly mentioning them in the pairing instruction.

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

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

The description provides explicit guidance on when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also advises pairing with related tools, giving clear usage context.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds that it fetches the page, extracts title/description/links, and outputs a single text blob. No contradictions, and it provides behavioral 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?

Three sentences: first states purpose, second explains process, third lists use cases. No unnecessary words, front-loaded with key information.

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

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

Given 2 params with full schema coverage, rich annotations, and no output schema, the description provides complete context: what it does, how it works, output format ('single text blob'), and use cases. No gaps.

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

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

Schema has 100% description coverage for both parameters. Description adds minimal value (e.g., 'Full URL', default/max for max_links) but does not significantly augment what schema already provides, 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 the tool generates an llms.txt file for any URL, with specific verb 'Generate' and resource 'llms.txt file'. It explains it fetches, extracts, and emits standard markdown, distinguishing it from sibling tools like 'scan_competitor_ai_presence' which have different purposes.

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

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

Explicitly lists three use cases: indexing a client's site, drafting own llms.txt, auditing competitors. Does not state when not to use, but the context is clear enough given the tool's specific function.

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

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

Describes return fields (event name, severity, etc.) and filter options, adding value beyond annotations which already declare readOnlyHint, idempotentHint, etc. No contradictions.

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

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

Two sentences, front-loaded with resource and then filters/return fields. No superfluous text.

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

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

Covers main purpose, filtering, and return values. With output schema and annotations, only minor missing details like pagination (though limit param is in 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 has 100% coverage, so description is not required to add much. Description summarizes filters but does not add new parameter-specific details 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 active NWS watches/warnings/advisories, with filtering options and return fields. However, it does not explicitly differentiate from sibling tool 'recent_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?

No guidance on when to use this tool vs alternatives like 'recent_alerts'. Only lists available filters but no context on when they are appropriate.

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 idempotent, read-only, non-destructive. Description adds meaningful context: data source (NWS), output structure (named periods, specific fields), and geographic restriction (US only). No contradictions.

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

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

Two concise sentences with front-loaded key information: 7-day NWS forecast, US lat/lon, and return format. No unnecessary words.

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

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

Given annotations and output schema exist, description is complete: mentions forecast duration, source, location restriction, and return fields. No gaps.

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

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

Schema covers both parameters with descriptions (US latitude, US longitude), so description adds no extra semantics. Baseline 3 is appropriate given 100% schema coverage.

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 7-day NWS forecast for a US latitude/longitude, specifying the return format (named periods with temperature, wind, text). This distinguishes it from siblings like get_hourly_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?

Description implies use for obtaining a 7-day forecast but does not explicitly state when to avoid or mention alternatives to siblings. Context signals show a sibling get_hourly_forecast, but no guidance on choice.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds the source (NWS) and duration (~168 hours) but does not disclose behavioral traits 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?

Two sentences, no filler. First sentence states the core functionality; second sentence lists use cases. Every word adds value. Ideal length for a simple 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 the simple parameters, full schema coverage, output schema present, and annotations, the description is largely complete. However, it does not clarify how this differs from sibling 'get_forecast', which could be a gap for agents choosing between similar 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 descriptions for all parameters. The description adds no extra meaning beyond the schema; it lists use cases but does not elaborate on parameter values or constraints. 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 retrieves hourly NWS forecasts for US lat/lon up to ~168 hours. It uses a specific verb (Get) and identifies the resource (hourly NWS forecast). It does not explicitly distinguish from sibling tool 'get_forecast', but the hourly aspect is clear from title and description.

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: 'short-term planning, severe-weather windows, or precipitation timing.' This helps agents decide when to use it. It does not mention when to avoid or alternatives, but the context is sufficient for typical scenarios.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by specifying that it returns the latest observation and listing the fields returned, providing context 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 a single concise sentence that provides all necessary information without extraneous words. It is front-loaded with the key action and resource.

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 presence of an output schema, the description adequately explains what the tool returns. It specifies that it returns the latest observation and lists key data fields. 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 description coverage is 100%, so the parameter is well-documented in the input schema. The description does not add new information about the parameter beyond what the schema provides, meeting the baseline expectation.

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 observation from a specific NWS weather station, listing specific data elements like temperature, humidity, wind, visibility, pressure, and present-weather codes. This distinguishes it from sibling forecast tools such as get_forecast and get_hourly_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 implies usage for current weather conditions by mentioning 'latest observation' but does not explicitly state when to use this tool versus alternatives like get_forecast or get_alerts. No exclusions or when-not-to-use guidance is provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds specific return fields (station IDs, names, time zones, coordinates) and geographic scope, which provides useful behavioral 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?

Two sentences: first states purpose with examples, second lists return fields and guidance. Front-loaded, no wasted words.

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

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

For a simple lookup tool with full schema and output schema, the description is complete. It covers purpose, return data, usage hint, and geographic limitation.

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 schema already describes both parameters (limit, state). Description reinforces state usage via examples but does not add new semantic details beyond schema.

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

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

Clearly states the verb 'Find' and resource 'NWS weather observation stations' with specific scope (US state). Includes examples and return fields, distinguishing it from sibling tools like get_observation and get_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?

Explicitly mentions 'use with get_observation' for workflow context and 'US only' as a constraint. Does not explicitly state when not to use, but the purpose is clear enough for 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 readOnly, idempotent, non-destructive behavior. The description adds value by detailing the fields returned (id, type, params, created_at, last_fired_at, fire_count) and implying scope (caller's subscriptions). No contradictions.

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

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

Two sentences: first sentence states purpose and return fields, second offers usage guidance. Front-loaded, no filler, 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?

For a simple listing tool with one optional parameter and no output schema, the description sufficiently covers what the tool returns and when to use it. No gaps remain given the low complexity.

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

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

Schema coverage is 100% with a well-described boolean parameter. The description does not add extra semantic value beyond what the schema already provides, hence 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 specifies a clear verb ('List') and resource ('the caller's active subscriptions'), and distinguishes from siblings like 'subscribe' and 'unsubscribe' by focusing on listing rather than adding or removing.

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

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

The description explicitly advises using this tool 'to review what you're monitoring before adding more or to find an id to cancel,' providing clear use cases. It does not explicitly mention when not to use it, but the context of siblings implies alternative uses.

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 key behaviors beyond annotations: 'Filing without an account returns a `claim_token`; pass it back later... to read whether it was fixed,' 'Rate-limited to 5 per identifier per day,' and 'Free; doesn't count against your tool-call quota.' The annotations (readOnlyHint: false, destructiveHint: false) are not contradicted; the description enriches them with concrete operational details.

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

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

The description is lengthy but every sentence carries distinct value — scope restriction, alternative redirection, token mechanics, rate limits, and roadmap impact. There is no filler, but it is dense and could be slightly more scannable. It is front-loaded with the core purpose and usage conditions, so structure is effective despite the length.

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

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

Given the tool has no output schema, the description adequately explains return behavior (claim_token and later status). It addresses edge cases (unsure which server, other vendors), rate limiting, quota implications, and the expected content format ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). The tool's position among siblings is also clarified by scoping feedback to this connection's 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 description coverage is 100%, providing baseline 3. The description adds meaningful usage semantics, especially around claim_token: it explains the round-trip flow and provides an example call format. It also clarifies the type parameter by tying categories to scenarios (bug, feature/data_gap, praise) beyond the schema's enum descriptions. Not every parameter is elaborated in the description, but the schema already handles those details.

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

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

The description clearly states the tool's function: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates the feedback types (bug, feature/data_gap, praise) and explicitly distinguishes itself from sibling tools by restricting use to tools served by this Pipeworx connection: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.'

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

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

Provides explicit when-to-use conditions: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also includes clear exclusions: 'if the tool came from a different MCP server... we cannot fix it and reporting it here only delays you; file it with that server instead.' This definitively guides the agent on both usage 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 cover safety. Description adds caching behavior (5min-1h), data source (CF analytics-engine), and no PII. Provides useful behavioral 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?

Three sentences plus bulleted use cases. Every sentence adds value; no redundancy. Front-loaded with core 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?

Low complexity (1 optional param, no output schema). Description covers purpose, use cases, data source, caching, and parameter semantics fully. No gaps.

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

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

Schema covers 100% with enum and description. Description adds further meaning by contrasting windows (hot vs steady-state). Adds value beyond schema.

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

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

Clearly states it returns top tools, top packs, and total call volume over a window. Three specific use cases differentiate it from siblings like discover_tools or ask_pipeworx.

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

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

Explicitly describes when to use: for discovering hot data, confirming canonical tools, and alignment checking. Implicitly excludes query-based tools via context, but no explicit 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 indicate read-only, open-world, idempotent, non-destructive. The description adds significant behavioral context: details on monotonicity checks, partition sum checks, semantic anchor (Jaccard similarity), partition filter (placeholder slugs), fill check against live CLOB depth, and response structure. 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 well-structured with a clear breakdown of modes, but it is somewhat long and includes some redundancy (e.g., cross-event mode explanation in two places). Every sentence adds value, but it could be slightly more concise without losing information.

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

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

Given the complexity (multiple modes, algorithmic details, response fields), the description is thorough. It covers all aspects: purpose, usage, behavior, parameters, output structure (enumerated), and even trading guidance. No output schema but the description compensates adequately.

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

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

Schema describes both optional parameters with 100% coverage. The description adds meaning: explains acceptable formats (slugs, URLs), distinguishes event vs topic modes, and describes the behavior triggered by each parameter. This goes beyond the schema's field descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes: no-args trending scan, event mode for specific slugs, and topic mode for cross-event scanning. This differentiates it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description explicitly tells when to use each mode: no args for trending, event for a specific market, topic for cross-event scanning. It provides examples of valid inputs (slugs, URLs, seed questions) and explains the cross-event mode catches patterns missed by single-event. It also advises when not to trade (if realizable_edge_pp ≤ 0).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint: false. The description adds rich behavioral detail: caching (1h KV-level keyed on knobs), response structure (by_segment, diagnostics), and the Fed bets exclusion note. 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 well-organized with clear sections (model families, response top-level, tradeable-edge knobs). It front-loads the purpose and uses bullet-like formatting. Some redundancy could be trimmed, but it's generally 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 high complexity (9 parameters, no output schema), the description thoroughly covers response structure, caching, diagnostics, and parameter interactions. It leaves the agent well-informed about what to expect and how to interpret empty segments.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond schema by explaining slippage_pp (Polymarket fees), max_spread_pp (tradeable-edge filter), min_partition_leg_kelly (partition arbs behavior), and context for default values. It does not cover all nuances but is substantial.

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 for opportunities where Pipeworx data disagrees with market price, and it's built for 'what should I bet on today'. This specific verb+resource+context distinguishes it from siblings like polymarket_arbitrage or polymarket_edge_tracker.

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 targets discovery for daily betting decisions and explains the model families and knobs. It does not provide explicit when-not-to-use or alternatives, but the context is clear enough for an agent to infer appropriate usage.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive traits. The description adds behavioral details beyond annotations: snapshot-based, 60-day TTL, daily closes, and explains response structure. 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 front-loaded with the core purpose and then details args and response format. Some parts are verbose (e.g., explanation of negative sign), but overall structure is logical and efficient for the complexity.

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

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

No output schema exists, but the description fully explains the return fields (tracked, expired, snapshot_dates) and their semantics. Also covers limitations (60-day TTL, daily closes). Given the tool's complexity and lack of output schema, the description is complete and self-sufficient.

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

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

Schema description coverage is 100%, and the description adds extra context: default values (days=14, window='1wk'), range (days 2-30), and examples. It clarifies how parameters affect the output, providing more meaning than the schema alone.

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 provides edge persistence and decay telemetry from daily polymarket_edges snapshots, answering how long an edge has existed and if it is shrinking. The verb and resource are specific, and it distinguishes itself from siblings like polymarket_edges (likely just current edges) and 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?

Description provides context for when to use the tool, e.g., comparing a fresh wide edge versus a 3-week-old wide edge, implying use cases for assessing decay. It does not explicitly list exclusions or alternative tools but gives enough context to infer appropriate usage.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint true, destructiveHint false. Description adds context by explaining it's a risk check that walks the order book ladder, and discloses potential loss modes, such as unhedged directional positions from partial fills.

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

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

The description is somewhat lengthy but well-structured with mode-specific sections and bullet-like lists. Every sentence adds value, though it could be slightly more concise without losing information.

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

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

Given no output schema, the description thoroughly explains return values (e.g., top_of_book, vwap_fill_price, profit_usd) for both modes. It covers defaults, edge cases, and risks, making it complete for the tool's complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the different interpretations of size_usd for single-market vs. basket, and the auto side logic for basket. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes and explicitly differentiates from sibling tools like 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?

Provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about thin books and the risk of partial basket fills.

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

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

Annotations (readOnlyHint, idempotentHint) are complemented by extensive detail on matching logic, safety fields, and edge cases (incompatible bet shapes, temporal mismatches). No contradiction with annotations; the description adds significant behavioral context.

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

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

The description is detailed and well-organized with clear sections (modes, response, safety fields). However, some sentences are lengthy and the text could be trimmed without losing key info.

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

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

Covers purpose, usage, response structure, and safety fields well. Lacks mention of error handling or behavior when both modes are provided, but overall comprehensive for a complex tool without output schema.

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

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

Schema coverage is 100% with descriptions, and the description adds override behavior and examples. The topic parameter lists shortcuts explicitly, and the explicit parameters include examples. Goes beyond the schema but could be slightly more concise.

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 computes cross-venue spreads between Kalshi and Polymarket for the same question. It distinguishes two modes (topic shortcuts and explicit tickers) and explains the response structure. This differentiates it from siblings like 'polymarket_arbitrage' (within-venue).

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 spreads are meaningful vs. not via compatibility_warning and temporal_alignment, and warns that most pre-mapped topics are not tradeable. However, it does not explicitly compare to sibling tools or state when not to use it (e.g., single-venue analysis).

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

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

Annotations already declare readOnly, idempotent, not destructive. Description adds scoping (by identifier) and that omitting key lists all keys. 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?

Three sentences: core function, use case with examples, scoping and related tools. No unnecessary words, front-loaded with key info.

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?

Completely covers input, output behavior, scoping, and related tools for this simple tool. No missing information given lack of 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 covers the single parameter fully. Description adds value by giving concrete examples of key usage and scoping. Baseline 3 uplifted to 4 due to added context.

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

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

Clearly states the tool retrieves a saved value by key or lists all keys if omitted. Provides concrete examples (ticker, address, notes) and distinguishes from siblings remember and forget.

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

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

Explicitly says when to use: to look up previously stored context without re-deriving. Mentions pairing with remember and forget, though lacks explicit 'when not to use' guidance. Still clear for agent.

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

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

Annotations already declare read-only, idempotent, and non-destructive. The description adds behavior like returning raw payload, mark_read affecting future calls, and polling being fine. Provides 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?

Five well-structured sentences with no redundancy. Front-loaded purpose, then parameter details, then usage advice. 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 5-parameter tool with no output schema, the description covers return contents, filtering, mark_read behavior, polling suitability, and alternative access. Feels complete for its complexity.

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

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

Schema coverage is 100% with descriptions. The description adds semantic details like example type ('sec_8k') and explains mark_read effect. Enhances understanding beyond schema.

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

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

The description clearly states it pulls fired events from the subscription feed, returns most recent alerts with source, citation_uri, and payload. It distinguishes from siblings by mentioning the alternative REST endpoint and focusing on feed-based 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?

The description explains filtering by type and since, setting mark_read for read tracking, and mentions polling suitability. However, it does not explicitly state when not to use this tool or compare with similar siblings like get_alerts.

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=true and idempotentHint=true. The description adds rich behavioral detail: fans out to SEC, GDELT/GNews fallback, USPTO soft-fail, date parsing, return structure with citations. 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 detailed but every sentence adds value. It is front-loaded with examples and organized logically. Slightly verbose but necessary given complexity.

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

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

Given the tool's complexity (multi-source, date handling, fallbacks, no output schema), the description fully explains return structure (changes[], total_changes, citation URIs) and usage boundaries. Nothing essential 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%, but description adds meaningful context: for 'since' it provides usage advice ("Use '30d' or '1m' for typical monitoring") and explains ticker vs. CIK for 'value'. For 'type' it clarifies only company is supported.

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 begins with clear usage examples ("What's new with X") and explicitly states the tool provides a change feed for a company. It distinguishes from sibling tool entity_profile by contrasting dynamic vs. static profile use cases.

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 examples and provides a clear alternative: "Use entity_profile instead when you want the static profile." It also explains fallback behavior (GDELT→GNews) and soft-fail for USPTO.

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

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

Annotations already indicate idempotentHint=true (safe to repeat), readOnlyHint=false (write), destructiveHint=false. The description adds that it stores key-value pairs scoped by identifier, and specifies persistence durations, providing useful behavioral 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 front-loaded with purpose, then provides usage context, behavioral details, and pairing with companions. No redundant sentences; each 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 the tool's simplicity (2 string params, no output schema), the description covers all necessary aspects: what it does, when to use, how it works (key-value, scoped, persistence), and related tools. It is complete.

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

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

Input schema has 100% coverage with clear descriptions for both required parameters (key, value). The description adds naming conventions for keys (e.g., 'subject_property', 'target_ticker') and value types ('findings, addresses, preferences, notes'), which enhances understanding beyond the schema alone.

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 across conversations/sessions, with concrete examples like 'resolved ticker, target address, user preference'. It explicitly mentions pairing with recall and forget, distinguishing it from sibling tools.

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

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

Provides explicit guidance on when to use: 'Use when you discover something worth carrying forward.' Also explains scoping by identifier, persistence differences between authenticated (permanent) and anonymous (24-hour) sessions, making it clear when and how 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?

The description discloses significant behavioral traits beyond annotations: every identifier is labelled with its source, unresolved identifiers are explicitly listed rather than omitted, LEI/FIGI enrichment degrades gracefully, and each call cascades through multiple endpoints. These details help the agent understand the tool's reliability and failure modes.

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

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

The description is fairly long but well-structured: it opens with example queries, states the core purpose, then provides usage guidance and detailed type information. The 'SUPPORTED TYPES' section is a dense run-on sentence, but every part earns its place given the tool's complexity.

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

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

Given no output schema, the description effectively explains what the tool returns (identifiers with source labels, unresolved field) and highlights input formats and graceful failure. It covers all essential contexts for an AI agent to decide when and how to invoke this tool.

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

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

Although the schema already covers both parameters fully, the description adds substantial meaning per type. For 'company' it details the cross-source identity spine (CIK, LEI, FIGI), and for 'drug' it explains RxCUI and citation behavior. The 'value' parameter is clarified with concrete examples (ticker, CIK, brand/generic names).

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

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

The description states a clear purpose: resolve a user-spoken name to canonical/official identifiers. It uses a specific verb ('resolve') and resource ('entity to IDs'), and distinguishes itself from siblings by framing itself as the prerequisite identifier lookup tool. The included example queries further illustrate intended usage.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains that the tool replaces 2-3 manual lookups. However, it does not explicitly name alternative tools for cases where an ID is already known or when other tools are more appropriate, so it falls short of a perfect 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 indicate safe, idempotent read behavior. The description adds valuable context: it probes each entity with ai_visibility_check, ranks by score, and returns score, confidence, and signal density per entity. 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 two sentences, front-loaded with purpose, and every sentence adds value. No unnecessary words or repetition.

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

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

Given the tool's complexity (4 params, 1 required, no output schema), the description fully covers what the tool does, how it works, what it returns, and a typical use case. It is complete for an AI agent to understand and invoke correctly.

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

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

Schema description coverage is 100%, so the schema itself documents all parameters thoroughly. The description does not add significant new information beyond what the schema provides, meeting the baseline expectation.

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

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

The description clearly states the tool compares AI visibility across multiple entities, uses ai_visibility_check, ranks by score, and surfaces most/least recognized. It is specific with verb 'compare' and resource 'AI visibility across multiple entities', and it distinguishes from sibling tool ai_visibility_check by focusing on side-by-side comparison.

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 a clear use case: 'competitive AI-marketing audits' with an example query. It implies this tool is for comparing multiple entities, while ai_visibility_check is for single entity checks. However, it does not explicitly state when not to use it or provide alternative tool 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?

The description discloses partial failure behavior (bundlephobia measurement delay, sources_failed list) and lists all return fields. This adds significant context beyond the readOnlyHint and idempotentHint annotations, giving the agent a clear understanding of tool behavior.

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

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

The description is slightly long but well-structured, starting with a high-level summary, then covering sources, usage, return values, limitations, and failure modes. It is front-loaded with the essential purpose and avoids unnecessary detail.

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

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

Given the absence of an output schema, the description adequately lists all return fields and explains the sources_failed mechanism. It also covers the ecosystem limitation, making the tool's behavior fully predictable for an agent.

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

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

Schema coverage is 100%, providing clear parameter descriptions in the schema. The description adds value by explaining the default behavior for the optional version parameter (defaults to latest) and reiterating scoped package acceptance.

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 composite check for adding npm packages, combining license, security, and bundle size analysis from deps.dev and bundlephobia. It specifies the npm ecosystem and distinguishes from potential alternatives by noting that other ecosystems fall under direct deps.dev:version calls.

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

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

Explicitly says to use when an agent asks about safety, popularity, or size of a package, and provides guidance for non-npm ecosystems by referring to deps.dev:version. This leaves no ambiguity about when to invoke this tool.

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

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

Discloses details beyond annotations: uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag, and output includes character offsets and similarity scores. Annotations already indicate read-only, idempotent, and non-destructive nature, which are consistent.

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

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

Single paragraph, front-loaded with main action, then provides usage guidance, technical details, and pairing. Every sentence adds value without fluff. Extremely concise and well-structured.

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

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

Despite no output schema, the description explains the return format (passages with offsets and scores). Covers input constraints, embedding model, and windowing strategy. For a search tool with clear inputs and well-described outputs, this is fully complete.

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

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

Schema coverage is 100% so baseline is 3. The description reinforces parameter meanings: adds max char limit for 'text', default and range for 'limit', and example queries for 'query'. This adds value but is not essential given 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 'Semantic search INSIDE a fetched record' and provides concrete examples (SEC 10-K, article, tool result). It distinguishes from sibling tool 'ask_pipeworx_grounded' by showing the pairing. The verb 'search' and resource 'within a source' are 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 says 'Use when the record is too big to cram into the prompt' and notes that passages carry offsets for verification. Pairs with 'ask_pipeworx_grounded' for grounding. Provides clear guidance on when to use this tool versus alternatives.

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

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

The description adds behavioral details beyond annotations: it returns a new subscription id, mentions the always-on feed, delivery channel limits (10/day SMS cap), webhook HMAC signing, and auto-disable after 10 failing runs. Annotations already indicate idempotent and non-destructive, so the description complements well.

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 unusually detailed but front-loaded with the main purpose and return type. It uses a structured format with examples and nested explanations. A minor trim could improve conciseness, but 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 no output schema, the description explains the return value (new subscription id). It covers auth requirements, supported types, delivery channels with constraints, and even notes about verification and caps. The tool is well-contextualized among 30+ siblings.

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?

With 100% schema coverage, the baseline is 3, but the description adds significant meaning: it provides concrete examples for each subscription type (e.g., items:['5.02'] for sec_8k), details the params object, and thoroughly explains the delivery channels including validation constraints and behavior.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses a specific verb (Create) and resource (subscription), and the detailed type list distinguishes it from sibling tools like list_subscriptions or unsubscribe.

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

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

The description explicitly states the requirement for a Pipeworx OAuth account and that anonymous/BYO cannot persist subscriptions. It provides clear context for when to use this tool but does not explicitly mention when not to use it or compare to alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, nondestructive. Description adds valuable behavioral context: returns categorized questions with exact tool shapes, drawn from a live catalog, and explains argument behavior. No contradiction.

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

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

The description is relatively long but every sentence contributes value: example queries, return format, argument behavior, usage guidance. Front-loaded with common user questions.

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

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

Despite no output schema, the description explains the return structure in detail (category-bucketed example questions with tool+argument shapes). Given the tool's single optional parameter and onboarding purpose, the description is fully 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% and the description adds examples ('finance', 'pharma', 'betting') and clarifies the effect of omitting the parameter. Provides more practical context than the schema alone.

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 category-bucketed example questions with tool+argument shapes, and explicitly distinguishes itself as the onboarding entry point for new agents, differentiating from siblings like ask_pipeworx and discover_tools.

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

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

Explicitly advises when to use: 'Use this FIRST when you do not yet know what Pipeworx can do'. Describes calling with no arguments or with a topic. Lacks explicit when-not-to-use but covers primary use case well.

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 details beyond annotations: ownership enforcement, deactivation (not deletion), and that historical events remain via recent_alerts. No contradiction with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true).

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, front-loaded with the action. Every sentence adds value with no wasted words.

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

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

Given the single parameter and lack of output schema, the description covers key behavioral aspects (ownership, deactivation, historical data). It could optionally mention the return value, but overall it is sufficiently complete for agent decision-making.

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%, and the parameter 'id' is well-defined in the schema. The description reaffirms its role but does not add new semantic value beyond the schema.

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

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

The description clearly states the action: 'Cancel a subscription by id' using a specific verb ('Cancel') and resource ('subscription'). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by detailing ownership enforcement and deactivation behavior.

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

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

The description provides clear context on when to use the tool: to cancel a subscription you own. It explains that ownership is enforced and that the row is deactivated, not deleted. While it does not explicitly list alternatives, the context implies appropriate usage.

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

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

Beyond annotations highlighting read-only/idempotent behavior, the description reveals key behavioral details: the automatic fall-through from structured to grounded pipeline, the specific verdict enum, and the crucial warning that could_not_verify means the check did not happen (not evidence for/against). This adds substantial value and does not contradict annotations.

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

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

The description is long but well-structured: starts with query examples to signal intent, then explains behavior, return values, and a critical caller warning. Each sentence earns its place, though a minor tightening could improve skim-readability without loss.

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

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

Given no output schema, the description thoroughly explains return values (verdict categories), evidence citation, and the meaning of error/special cases. It also covers the two execution paths and replacement value. This is complete for a complex tool even with strong annotations.

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

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

Schema already covers both parameters with descriptions (100% coverage). The description adds meaning by explaining tolerance_pct overrides the implied tolerance, caps at 5 by default, and can be set to 1–2 for hallucination detection. It also provides realistic claim examples for the claim parameter, enhancing 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 defines a specific verb+resource: 'natural-language claim verification against authoritative sources' and explains the two distinct pipelines (SEC EDGAR for company-financial claims, grounded pipeline for others). It distinguishes itself from sibling Q&A tools by focusing on verifying factual claims with explicit verdicts, not just answering questions.

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 'Use whenever the agent needs to check whether something a user said is factually correct', and it clarifies the two routing paths based on claim type. It mentions it 'Replaces 4–6 sequential calls', implying when not to use alternative pipelines, but lacks an explicit 'don't use for deep research' exclusion. Still, context is clear.

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