Data Cincinnati

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true. The description adds significant behavioral context: it makes calls to external APIs (Anthropic), details cost implications (BYO key, pay directly), describes the output structure (per-model score/confidence/signals/raw_response + combined view), and explains default model behavior. No contradictions.

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

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

The description is a single, well-structured paragraph that front-loads the main action, then provides parameter specifics, followed by use cases. Every sentence adds value with 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 4 parameters, no output schema, and annotations, the description covers core functionality, parameter details, output format, and use cases. It briefly mentions 'signals' without elaboration, which is minor. Overall, sufficiently complete for a probe 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 descriptions cover 100% of parameters. The tool description adds extra meaning by explaining parameter purpose, examples (e.g., 'Pipeworx'), and usage tips (supported models, optional context for disambiguation). This provides value 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's purpose: probing LLMs for knowledge about an entity and scoring visibility (0-100) per model. It uses specific verbs ('probe', 'score') and resource ('LLMs'), and distinguishes itself from sibling tools like deep_research or compare_entities.

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

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

The description provides explicit use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains default model and requirement for Anthropic API key. However, it lacks explicit when-not-to-use or alternatives among the many sibling tools.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior, so the description only needs to add non-obvious context. It does so by describing internal routing behavior, argument filling, structured answers, stable citation URIs, and fast single-call execution. This gives the agent a meaningful behavioral model beyond the schema.

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

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

The description is long but front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and packed with high-value examples and routing rules. The later section becomes slightly run-on and redundant ('START HERE' followed by 'default entry point...'), but every sentence still contributes to selection or invocation.

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 rich annotations, a simple one-parameter schema, and no output schema, the description provides enough context to invoke the tool correctly: what to send, when to use it, what it returns, and how it compares to siblings. It does not specify exact response formatting, but the structured-answer-with-citations description is sufficient for an agent.

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

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

Schema description coverage is 100%: the 'question' parameter is described as accepting natural language and all aliases are individually documented. The description reinforces this with examples and usage guidance but adds no new parameter-level semantics, so it meets the baseline without exceeding it.

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

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

The description clearly identifies the tool as an authoritative data-query router: it takes natural-language questions, routes them across 5,798 tools and 1,517 verified sources, and returns structured answers with pipeworx:// citation URIs. This goes well beyond a generic 'ask a question' phrasing and distinguishes it from plain web search.

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

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

The description explicitly says to prefer this tool over web search, gives concrete trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), and provides six real examples. It also names sibling alternatives and tells the agent when to use them: ask_pipeworx_grounded for hallucination-sensitive single answers and deep_research for broad/multi-part questions.

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 the safety profile (read-only, open-world, idempotent, non-destructive), so the description's job is to add what annotations cannot express. It discloses that this is a live beta whose routing may change at any moment when a candidate is under test, that no candidate is active as of 2026-07-26 so behavior currently matches ask_pipeworx exactly, and that it 'Falls back to nothing — this IS a full working router'. These changeability and parity facts are materially important for call expectations.

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, and each one earns its place: identity/parity, current candidate state, usage condition, and fallback clarification. Key facts are front-loaded, and the parenthetical retirement date and tool count are informative rather than padding, though slightly dense.

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 a single semantically-relevant parameter, rich annotations, and no output schema, the description covers what the tool does, its current live state, when to prefer it, and points to the response shape via 'same response shape' as ask_pipeworx. The one gap is that the return format is only referenced indirectly by parity rather than described, but the explicit identical-to-stable statement makes that pointer 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%: all six parameters are documented as aliases for the single required 'question' string, so the schema fully carries parameter meaning. The description only repeats 'same arguments' as ask_pipeworx, which reinforces consistency but adds no semantic detail beyond the schema. The baseline 3 applies since the description does not need to compensate.

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 defines the tool concretely as the 'Beta version of ask_pipeworx' and 'identical universal router (same 5,798 tools, same arguments, same response shape)', naming a specific operation (universal routing of a question to one of 5,798 internal tools) and resource. It also distinguishes this tool from siblings by positioning it as 'the experimental edge' versus the stable router, so an agent can tell it apart from ask_pipeworx and ask_pipeworx_grounded.

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

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

Explicit when-to-use guidance is present: 'Use it exactly like ask_pipeworx when you want the newest routing' — the condition being a desire for experimental routing improvements. The alternative is named ('results are compared against the stable router'), but the description stops short of an explicit when-not-to-use instruction such as 'use ask_pipeworx for stable behavior', so the exclusion is implied rather than stated.

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, and the description adds substantial behavioral context beyond that: it only answers from fetched tool results, returns verbatim evidence, can explicitly refuse with enumerated refusal_reason values, and costs one extra LLM call. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: mode, behavior, return shape, refusal reasons, use cases, and cost comparison. It is front-loaded with the key concept and avoids 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?

Because there is no output schema, the description fully specifies the success and refusal return shapes, including the refusal_reason enum. It also covers the routing behavior, evidence format, cost tradeoff, and selection guidance, making the tool fully callable by an agent.

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

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

Schema description coverage is 100%, and the input schema already documents the question parameter plus all aliases thoroughly. The description does not add much parameter-level meaning, but it does not need to; the schema carries the load.

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

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

States a specific verb and resource: 'hallucination-resistant answer mode' for ask_pipeworx, and clearly distinguishes itself from ask_pipeworx by describing the grounded extraction process and refusal behavior. It names its sibling ask_pipeworx and explains what makes this variant different, so an agent can tell them apart.

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

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

Explicitly says to use this tool when an answer will be quoted, cited, or acted on and when fact invention is unacceptable, then gives the alternative: 'prefer ask_pipeworx for casual lookups.' This is direct when/when-not guidance with a named sibling alternative.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses rich behavior: market resolution, classification, parallel fan-out, response shapes, resolver contract with match confidence and alternatives, parent event extraction, fallback logic for news, safety short-circuits, closed market handling, wide spread tradeability, and cancellation rule parsing. 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 comprehensive but very lengthy, containing many paragraphs and sections. While all content is valuable, the lack of bullet points or structured formatting makes it harder for an agent to quickly parse. It is informative but not concise, earning a mid-range score.

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

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

Given the tool's complexity (multiple classifiers, fan-out logic, response shaping, edge cases), the description covers all essential aspects: input formats, process steps, response shapes, resolver contract, parent event extraction, news fallback, safety mechanisms, closed market behavior, wide spread handling, and cancellation rules. No output schema exists, so the description adequately explains return values.

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

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

Schema coverage is 100% with clear parameter descriptions. The tool description adds operational context (e.g., depth options: quick vs thorough, include_raw trade-off) and examples of fan-out, but the core semantics are already well-covered by the input schema. The description enhances understanding without being essential for parameter definition.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input type (slug, URL, question text) and outlines the process (resolve, classify, fan out, return evidence and comparison). This distinguishes it from sibling tools like popymarket_arbitrage or ask_pipeworx, which serve 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?

The description provides explicit usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also details when the tool short-circuits (low confidence, closed markets, wide spreads) and explains resolution-rule risks. However, it does not explicitly state when not to use this tool or suggest alternative tools, slightly limiting guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, providing high transparency. The description adds context about the source system and return fields, which is useful but not critical beyond annotations. No contradictions.

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

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

Two sentences with no waste. Every word adds value: specifies catalogue, keyword search, return types, and relationship to cincinnati_query. Front-loaded with the core action.

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 explicitly states what is returned (names, descriptions, resource IDs). It omits pagination behavior and error conditions, yet given the schema coverage and annotations, the description is largely sufficient for a straightforward search 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%, with clear parameter descriptions for limit, query, offset, and apiKey. The tool description does not add additional meaning beyond what the 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 searches the Cincinnati open-data catalogue by keyword and returns dataset names, descriptions, and Socrata resource IDs. It references specific resources (data.cincinnati-oh.gov) and distinguishes from sibling tools like cincinnati_query and cincinnati_recent by mentioning the return of resource ids for use with cincinnati_query.

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

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

The description explains when to use the tool (search for datasets by keyword) and how output relates to cincinnati_query. It does not explicitly state when not to use or list alternatives beyond the implied workflow, but the context is clear enough for an agent to decide.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds optional _apiKey context for rate limits, which is useful beyond annotations. No contradictions.

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

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

Two sentences, front-loaded with the primary action, no wasted words. Efficiently communicates all necessary information without verbosity.

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 query tool with comprehensive annotations and 100% schema description coverage, the description covers all essential aspects: data source, resource ID format, query clauses, and key parameter nuances. No output schema needed as per rule.

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 3. The description goes beyond by listing SoQL clauses (where/select/group/order/limit/offset) and explaining the _apiKey parameter's purpose for higher rate limits, adding value over 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?

Description clearly states the tool runs a raw SoQL query against Cincinnati open-data resources, specifies the data source URL and the 8-character resource ID format, and distinguishes it from sibling tools cincinnati_datasets and cincinnati_recent by mentioning their respective uses.

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

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

Explicitly provides guidance on when to use cincinnati_datasets to find a resource ID or cincinnati_recent for common ones, and by implication when to use this tool directly for raw queries, satisfying the agent's decision-making needs.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, etc. The description adds context about returning newest-first and SoQL filtering, which aligns with and extends the annotation information.

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 concise sentences front-load the purpose, provide usage guidance, and clarify parameters, 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?

The description covers the tool's purpose, inputs, and behavior (newest-first), but lacks details on output structure; however, for a simple records tool, this is 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%, so baseline is 3. The description adds value by clarifying that _apiKey is optional for higher rate limits and that dataset uses friendly names, enhancing understanding beyond the schema.

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

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

The description clearly states the tool retrieves recent records from a Cincinnati open dataset using friendly names, distinguishing it from the sibling cincinnati_query tool.

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 recommends using this tool over web search for specific queries and directs users to cincinnati_query for anything else, providing clear when-to-use and when-not-to-use guidance.

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

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

Adds significant behavioral context beyond annotations: describes data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, and result sorting. 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?

Description is dense but well-structured with example queries upfront. Each sentence adds value; no wasted words. Could be slightly more organized, but still effective.

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

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

Despite no output schema, description mentions return format ('paired data + pipeworx:// citation URIs per entity'). Could specify exact fields returned, but sufficient for understanding.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context about what data each type pulls (e.g., 'revenue + net income + cash + long-term debt' for companies), enhancing parameter understanding beyond enum values.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, with specific data sources per type. It distinguishes from siblings like entity_profile by emphasizing parallel vs 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?

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and provides example queries. Clearly defines 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?

Annotations cover read-only, idempotent, open-world, and non-destructive traits, and the description adds substantial behavior: parallel decomposition across 5,798 tools, findings packet contents, gaps[] never invented, contradiction scan, hop field, fetchable citation_uri, semantic excerpting, and latency expectations. 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?

Front-loaded with auth requirement and core purpose, but the description is long and slightly repetitive, with citation/findings details appearing multiple times. It earns most of its length through genuinely useful operational details, though tighter editing would improve it.

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

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

For a complex tool with no output schema, the description is remarkably complete: it explains auth tiers, alternatives, output format, citation resolvability, gaps behavior, depth meanings, and expected latency. An agent has everything needed to select and invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters; the description adds value by elaborating depth modes (quick single-hop vs standard gap recovery vs thorough paid iterative hop) and clarifying that the question parameter is meant for broad/multi-part natural language. This is useful context beyond the schema, though not required for basic invocation.

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

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

The description names a specific action (grounded multi-source research) with a clear resource scope (1517 structured data sources, not open-web search) and distinguishes it from ask_pipeworx for single lookups. It also states the decomposed parallel research behavior and output, which fully separates it from siblings.

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

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

It explicitly says to use ask_pipeworx when not signed in, recommends deep_research for broad/multi-part questions over structured data, and directs single lookups to ask_pipeworx. This provides both positive and negative usage guidance with a named alternative.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds valuable context: returns top-N relevant tools with full input schemas and examples, ready to call directly, with no second lookup needed. 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 reasonably concise given the complexity. It front-loads the purpose and then adds usage guidance and return format details. Every sentence adds value, though could be slightly tightened.

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

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

There is no output schema, but the description thoroughly explains that the tool returns top-N tools with names, descriptions, schemas, and curated examples, and that results are directly callable. This covers the essential output context for a discovery 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%, so the baseline is 3. The description mentions query aliases (task, q, description, search) but this is partially redundant with schema. No additional semantic depth beyond what the schema provides.

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

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

The description explicitly states the tool discovers tools by describing data or task, lists many domains (SEC filings, FDA drugs, etc.), and distinguishes from siblings by advising to call it first to see 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?

Clearly indicates when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and includes a strong directive: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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?

Despite annotations declaring readOnly/openWorld/idempotent/non-destructive, the description adds substantial behavioral context: it fans out across many sources, returns sources_used/sources_failed, treats empty sections as real 'no data,' soft-fails on the USPTO sunset, and explains that a lack of FDA products is expected for small-molecule-only companies. These details go far 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 it earns its length given there is no output schema and the tool spans many sources. It is front-loaded with the core purpose and usage preference, then systematically covers return sections and input semantics. It could be slightly better organized with bullets or shorter sentences, hence not a 5.

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

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

For a complex multi-source tool with no output schema, the description is remarkably complete. It documents all major return sections, input types, expected empty results, soft-failure behavior, and private-company handling. An agent has enough context to invoke the tool correctly and interpret unusual results without external guidance.

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

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

Schema coverage is 100%, but the description significantly enriches both parameters: it clarifies that 'company' and 'ticker' are interchangeable, explains that 'value' can be a ticker, zero-padded CIK, or name, and describes resolution behavior including resolved_from/resolved_to and the private-company failure mode. This greatly exceeds 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 opens with concrete user phrasings and states the core action: 'full cross-source profile of a US public company in ONE parallel call.' It clearly names the resource (SEC EDGAR, XBRL, patents, contracts, FDA, H-1B, news, GLEIF) and distinguishes itself from chained single-pack lookups, making its purpose unambiguous.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' which gives a clear when-to-use signal. It also explains accepted inputs and the private-company edge case. It does not name every sibling alternative or explicitly state when not to use it, so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true. Description confirms destructive action ('Delete') but adds no extra 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 covering purpose, usage guidelines, and sibling references. Every sentence adds value; front-loaded with main action.

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

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

Simple tool with one required parameter and no output schema. Description fully covers purpose, usage context, and destructive nature, supported by 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?

Single parameter 'key' is fully described in schema; description adds no additional meaning 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?

Description clearly states action (Delete) and resource (previously stored memory by key). Also distinguishes from siblings by referencing 'remember' and 'recall'.

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

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

Explicitly states when to use: when context is stale, task done, or clearing sensitive data. Mentions pairing with related tools, but no explicit when-not 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 provide readOnly, idempotent, and non-destructive hints. The description adds behavioral details: fetches the page, extracts content, and emits standard markdown. This complements annotations without contradiction.

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

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

The description is concise (three sentences plus a use-case line) with immediate purpose statement. No unnecessary words or repetitions; each sentence contributes value.

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

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

Given the simple tool (2 params, no output schema), the description covers behavior (fetch, extract, output), use cases, and output format. It lacks error handling or rate limit info, but annotations cover safety. Adequate for the 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 (url, max_links) are described in the schema. The description does not add meaning beyond the schema; it only repeats the purpose indirectly. 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 it generates an llms.txt file for any URL, specifying output format (markdown), extracted elements (title, description, key links), and use cases. This distinguishes it from sibling tools like ai_visibility_check and scan_competitor_ai_presence by focusing on file generation.

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

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

The description lists three explicit use cases (indexing client sites, drafting own llms.txt, auditing competitors), giving clear context. However, it does not explicitly state when not to use this tool or mention specific alternatives among siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and nondestructive. The description adds return field details and default filtering, but this is moderate incremental value.

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 with no wasted words. It states the purpose, return fields, and usage guidance upfront.

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

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

Given no output schema, the description lists return fields. With one parameter and strong annotations, it covers essential behavioral and structural aspects. Minor omission like pagination is not critical.

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

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

Schema coverage is 100% with a clear description for 'include_inactive'. The description does not add further parameter info, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists active subscriptions, using a specific verb-resource combination. It distinguishes from sibling tools like subscribe and unsubscribe which perform different actions.

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

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

The description advises using the tool to review current subscriptions before adding more or to find an id to cancel. This provides clear context, though no explicit when-not or alternatives are given.

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 are all false, so the description carries the full burden of explaining external side effects. It discloses rate limits ('Rate-limited to 5 per identifier per day'), quota impact ('doesn't count against your tool-call quota'), the claim_token flow for chained reads, and that 'The team reads digests daily and signal directly affects roadmap.' This goes well beyond what annotations convey.

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

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

The description is dense but not bloated; every sentence serves a purpose from usage conditions to rate limits. It front-loads the core purpose and then logically flows through exclusions, framing advice, token behavior, and operational guarantees. It is longer than average but earns its length given the tool's nuanced multi-mode behavior.

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, the description fully explains expected return behavior (claim_token on filing, later status read), covers all parameter semantics via the schema, and includes operational context (rate limit, quota, digest review). It also distinguishes when not to use the tool, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful usage semantics on top of the schema: it explains the claim_token lifecycle ('Filing without an account returns a `claim_token`; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and instructs how to frame message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This enriches the parameter understanding beyond the 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 opens with a clear, specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately distinguishes this tool from siblings like ask_pipeworx or discover_tools by framing it as feedback submission rather than inquiry or discovery.

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

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

Explicitly lists trigger 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 gives a clear exclusion rule: feedback about other MCP servers should be filed with that server, and provides a test ('Pipeworx tool names are the ones this connection lists') to disambiguate.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds caching behavior (5min-1h depending on window) and data provenance (CF analytics-engine, no PII), which provide useful 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 compact, front-loaded with purpose, followed by use cases and technical details. Every sentence adds value without redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description covers all needed context: return contents, use cases, window behavior, data source, and caching. No gaps identified.

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

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

Only one parameter (window) with 100% schema coverage. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' which complements the enum values.

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

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

The description clearly states it returns top tools, top packs, and total call volume over configurable windows. It distinguishes from sibling tools like ask_pipeworx or discover_tools by focusing on trending/popularity analytics.

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

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

Three concrete use cases are listed: discovering hot data sources, confirming canonical tools, and aligning use cases. Window choice guidance is provided, but no explicit 'when not to use' or contrast with siblings beyond implicit differentiation.

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 detailed behavioral traits: Jaccard similarity threshold (≥0.30), placeholder filter, fill check against CLOB depth, and output structure. Annotations already indicate read-only, open world, idempotent; description adds meaningful context without contradiction.

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

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

Description is lengthy (~300 words) but well-structured with clear sections and examples. Every sentence adds value, though slightly more concise presentation could improve scanning efficiency.

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?

Thoroughly covers all aspects: modes, checks, output fields, and trading advice. Despite lacking an output schema, the description explains the response structure and provides sufficient context for the agent to understand tool behavior and results.

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

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

Schema coverage is 100%, but description adds substantial meaning: explains event slug usage with examples, topic as seed question, and that no args yields trending scan. Provides clear semantics beyond minimal 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?

Description explicitly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks. Clearly distinguishes between scanning modes (no args, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Provides explicit when-to-use guidance: no args for trending scan, event for specific market, topic for cross-event scanning. Explains when not to trade (realizable_edge_pp ≤ 0) and refers to polymarket_fill_risk for custom sizing.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds extensive behavioral details: cache behavior (1h KV-level), slippage assumptions, per-model-family calculations, diagnostics for empty segments, and per-opportunity fields like edge_pp_net and kelly_fraction. 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?

Purpose is front-loaded, but the description is very long and dense with technical details. While well-structured with sections and enumerated model families, it could be more concise. Some details (e.g., exact alpha values) may be excessive for initial selection.

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

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

For a complex tool with 9 parameters and no output schema, the description thoroughly covers response structure (by_segment, diagnostics, fed candidates), per-opportunity fields, and knob effects. It compensates fully for missing output schema and guides proper usage.

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

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

All 9 parameters have schema descriptions, so baseline is 3. The description adds value beyond schema by providing practical usage hints (e.g., slippage_pp explains typical bid/ask, min_partition_leg_kelly explains why min_kelly doesn't apply). Minor redundancy but overall helpful.

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, with a specific use case 'what should I bet on today'. It distinguishes itself from siblings through detailed model families and segments that are unique to this tool.

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 context on when to use (discovering opportunities without paging) and how to use via tradeable-edge knobs. However, no explicit mention of alternatives or when not to use it, especially among sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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, idempotentHint=true, destructiveHint=false. Description expands significantly: explains it reads snapshots, lists response fields (tracked, expired, snapshot_dates), details decay calculation ('daily closes of edge_pp_net, not intraday'), and discloses limits (60-day TTL, snapshot start time). 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?

Front-loaded with purpose and key question. Uses efficient structure: starts with purpose, then explains with concrete examples, lists response fields in a readable format, and concludes with limitations. Every sentence adds value; no filler.

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

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

Despite no output schema, the description thoroughly explains all response fields (tracked, expired, snapshot_dates) with their sub-fields, and covers input parameters and limitations. For a complex tool, this is complete and leaves no obvious gaps.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds default values (days=14, window='1wk'), valid ranges (days clamp 2-30), and clarifies window as 'snapshot family', providing meaning beyond the schema.

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

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

Description clearly states the tool's purpose: 'Edge persistence and decay telemetry' answering 'how long has this edge existed and is it shrinking?'. It specifies the resource (daily polymarket_edges snapshots) and verb (provides telemetry), distinguishing it from siblings like polymarket_edges (raw snapshots) and polymarket_arbitrage (different angle).

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 context on when to use the tool via examples (fresh wide edge vs. old wide edge) and explains output fields. However, it does not explicitly state when not to use or name alternative tools for different needs, though the unique focus on persistence/decay is implied.

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 concrete behavioral detail: it requires one of market or event, walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns that partial basket fills create unhedged directional risk. 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 well-structured. It front-loads the core purpose, then uses clear section headers (SINGLE-MARKET, BASKET). Every sentence adds essential detail for correct invocation. Could be slightly trimmed, but the length is justified by 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 comprehensively explains return values for both modes, including edge cases (thin_legs, forced_directional_risk). It also covers error states (cannot_fill verdict) and parameter constraints. This is a complete and actionable description.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond parameter names/types. For side, it explains default auto based on partition sum. For size_usd, it distinguishes meaning between single-market (spend/proceeds) and basket (settlement notional) and documents clamp range. This is high-value 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?

The description clearly states the tool performs a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes two modes (single-market and basket) and uses specific verbs and resource nouns. This differentiates it 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?

Explicitly states when to use: before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or polymarket_edges trade above ~$500. It also warns against partial basket fills converting arb to directional position, effectively telling the agent when not to proceed without checking.

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?

Even though annotations already mark this as read-only and idempotent, the description goes well beyond them: it discloses that legs are matched by keyword/word overlap, that `pairing_unverified` is always set when pairs are returned, that unknown metric types are never paired, and that fees are not modeled. It also clarifies the nuanced meaning of `temporal_alignment_unknown` and `null` alignment, which prevents misinterpretation.

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

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

The description is long and dense, but each section (modes, response, safety fields, fees, skipped counters) adds necessary information, especially with no output schema present. It is front-loaded with the core purpose and mode distinction. Minor redundancy exists, such as repeated emphasis on unverified pairing and temporal alignment caveats, which keeps it from being maximally concise.

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

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

Given the tool's complexity, the lack of an output schema, and the need to correctly interpret compatibility warnings, this description is remarkably complete. It covers return shape, safety fields, code semantics, fee treatment, skipped-leg counters, and realistic expectations about tradeability. An agent has everything needed to invoke the tool correctly and interpret its results.

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

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

Schema coverage is 100%, giving the description a baseline of 3, but it adds substantial meaning: `topic` enumerates all shortcuts and explains auto-mapping, while explicit ticker/slug parameters are described as overrides for the topic-mapped side. This tells the agent exactly how the three parameters interact beyond their raw schema types.

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

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

The description states a specific resource and scope: the cross-venue spread between Kalshi and Polymarket for the same resolving question. It is clearly differentiated from single-venue siblings by emphasizing cross-venue comparison and the same-question constraint. The two modes (topic vs explicit ticker/slug) make the tool's purpose immediately actionable.

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

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

The description gives clear internal usage guidance: use `topic` for pre-mapped shortcuts or explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings, and both modes use the same matcher. It also warns that pre-mapped topics are not automatically tradeable and that spreads are gross, not net. However, it does not explicitly contrast this tool with closely related siblings like polymarket_arbitrage or polymarket_edges.

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

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

Adds scope (scoped to identifier) and behavior when key omitted beyond annotations (readOnlyHint, idempotentHint, destructiveHint). 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?

Concise, front-loaded with main action, no unnecessary words. Every sentence adds value.

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

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

Covers purpose, usage, scope, and sibling relations adequately for a simple read-only tool with one optional parameter and no output schema.

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

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

Schema coverage is 100% and description repeats schema info (omit key to list all). No additional parameter 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 the tool retrieves a saved value or lists keys, with examples and context. Distinguishes from siblings like 'remember' and 'forget'.

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

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

Provides clear when-to-use guidance (look up stored context) and mentions pairing with remember/forget. No explicit when-not, but sufficient for simple 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?

Beyond annotations (readOnly, idempotent, non-destructive), the description details key behaviors: returning specific fields, filter support, the mark_read flag affecting subsequent calls, and that polling is acceptable. 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 concise with 4 sentences, each adding distinct value: purpose/output, filtering, mark_read behavior, and alternative access. No irrelevant information; front-loaded with the main action.

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 (5 params, no output schema), the description sufficiently covers the purpose, output fields, filtering, mark_read effect, and polling suitability. It compensates for the missing output schema by hinting at the structure.

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 decent descriptions for each parameter. The description adds an example filter value ('sec_8k') and reinforces the 'since' parameter as ISO timestamp, but repeats much of the schema info. The added value is modest.

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 pulls fired events from the subscription feed and returns recent alerts with specific fields (source, citation_uri, payload). It distinguishes itself from sibling tools like list_subscriptions by focusing on fired events rather than subscription metadata.

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 context on when to use the tool (pulling alerts and filtering) and mentions an alternative HTTP access method for scripts. However, it does not explicitly state when not to use the tool or compare directly with other tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds detail about fan-out behavior, fallback from GDELT to GNews, and patent soft-failure. Output structure is also described. No contradictions with annotations.

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

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

The description is a single paragraph, well-organized with examples, source details, and a clear alternative tool mention. Every sentence adds value without redundancy.

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

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

Given the tool's complexity (multiple data sources, fallback logic, parameter formats), the description covers all relevant aspects. It mentions output structure despite lacking an output schema, and references a sibling for alternative use cases.

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

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

Schema coverage is 100%, but the description adds valuable context: explains that `type` is only 'company', `value` accepts ticker or CIK, and suggests typical values for `since`. This goes beyond the schema's own 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 provides a change feed for a company in a recent time window, covering SEC filings, news, and patents. It distinguishes itself from the sibling tool entity_profile, which provides static profiles.

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

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

Explicit example queries ('What's new with X') are given, along with when to use entity_profile instead. Guidance on the `since` parameter (ISO date or relative shorthand) and typical monitoring values 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?

Adds context beyond annotations: explains that it is a write operation (not readonly), idempotent, non-destructive, and specifies persistence (authenticated users get persistent memory, anonymous sessions 24h). No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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

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

Front-loaded with core purpose, then usage guidance, then behavioral details. Every sentence adds value; no redundancy. Efficient 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?

Given tool complexity (2 params, no output schema), the description fully covers usage, behavior, persistence, and pairing with related tools. No gaps for an agent to correctly select and 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?

Schema coverage is 100% with clear descriptions for key and value. The description adds value by suggesting naming conventions (e.g., 'subject_property', 'target_ticker') and specifying that value can be any text, which 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 'Save data the agent will need to reuse later' and gives concrete examples like resolved ticker, target address. It distinguishes from siblings by mentioning 'recall' and 'forget' as companion 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 when you discover something worth carrying forward') and pairs with 'recall' and 'forget' for retrieval and deletion, providing clear guidance on selection vs 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 mark the tool read-only and idempotent, and the description adds substantial behavioral detail: identifiers are source-labelled, unresolved identifiers appear under 'unresolved', ambiguous matches return 'figi_candidates', and LEI/FIGI enrichment degrades gracefully if upstream services fail. No contradiction with annotations.

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

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

The description is long but front-loaded with purpose and examples, then organized by supported type. Each parenthetical addresses a real edge case or decision point rather than padding, and no sentence feels extraneous for this level of 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?

For a two-parameter tool with no output schema, the description supplies enough context: what identifiers are returned per type, what happens on ambiguity, what happens on enrichment failure, and how to format inputs. An agent selecting or invoking the tool would not need external lookups.

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?

Even though the schema covers both parameters 100%, the description adds critical semantics: pass only the entity name, use the exact issuer string for bonds, trailing security words match nothing, and accepted inputs include ticker, CIK, ISIN, or name. This materially reduces the chance of mis-invocation.

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

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

The description names a concrete action—resolving a user-spoken name to canonical/official identifiers—and enumerates supported entity types (company, drug) with example queries. It clearly frames this tool as the ID-from-name lookup among the sibling tools.

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

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

It gives an explicit trigger: 'Use FIRST whenever you have a name but need an ID,' and provides detailed guidance for ambiguous bond names, non-ticker instruments, and drug names. It does not explicitly name alternative tools or state when not to use it, so it falls just short of full routing guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: probes each entity via `ai_visibility_check`, ranks by score, and surfaces most/least recognized, along with output fields (score, confidence, signal density). No contradictions.

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

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

Two sentences: first defines action and resource, second gives usage rationale and output structure. Front-loaded with core purpose, no filler.

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

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

Given 4 parameters (all described), no output schema, and rich annotations, the description covers purpose, underlying mechanism (proxy to another tool), and result format. No gaps for this complexity level.

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

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

Schema coverage is 100%, so parameter descriptions exist. The description adds semantic value by noting the first entity is treated as 'subject' for narrative, which is not in the schema. This enriches agent understanding.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using a specific verb 'compare' and resource 'AI visibility of entities'. It distinguishes from sibling `ai_visibility_check` by emphasizing multi-entity comparison and ranking.

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 contextualizes use for competitive AI-marketing audits with an example question. It implies when to use (competitive analysis) but doesn't explicitly state when not to use or name alternatives beyond the implied single-entity check.

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

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

Annotations provide readOnlyHint, idempotentHint, etc. The description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list if it times out. 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 information-dense and front-loads the key purpose. Every sentence adds value, including return structure and error handling. However, it is relatively long; a slightly more compact version could be made without losing content, but it's still well-structured.

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

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

Given no output schema, the description fully details the return structure (summary block, per-advisory detail, links, alternative versions). It also covers ecosystem scope, partial failures, and timing expectations, making it complete for an agent to understand what to expect.

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

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

Input schema has 100% description coverage, and the descriptions in the schema already explain both parameters clearly. The tool description does not add significant new meaning for parameters beyond repeating 'npm package name' and 'specific version', so it provides no extra value beyond the rich schema.

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

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

The description clearly states the tool's purpose: a composite check for npm packages covering license, advisories, version history, and bundle size. It uses specific verbs like 'fans out' and 'check' and distinguishes itself from siblings by explicitly stating 'NPM ecosystem only' and referencing deps.dev for other ecosystems.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also specifies limitations and alternatives: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Annotations already cover safety traits (readOnlyHint, idempotentHint, etc.). The description adds technical details beyond annotations: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K char limit with truncation flagging. This fully discloses behavioral traits.

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 pack a lot of information efficiently, though the first sentence is somewhat dense and could be split for readability. No wasted words, but minor structural improvement possible.

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, offsets, scores). It covers input limits, technical behavior, and usage context, making it complete for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description enriches each parameter: 'text' gets its max size, 'query' gets example natural-language queries, 'limit' gets default and range. This adds meaning beyond the bare schema descriptions.

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

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

The description clearly states the tool performs 'Semantic search INSIDE a fetched record', provides concrete examples (SEC 10-K, article), and specifies the output (top-N passages with character offsets and similarity scores). It distinguishes itself from siblings by mentioning its pairing with ask_pipeworx_grounded.

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

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

Explicitly tells when to use: 'when the record is too big to cram into the prompt' and contrasts with an alternative approach ('fetch with the gateway, ground over the relevant passages instead of the whole document'). Also includes a cap (200K chars) and a truncation behavior, guiding 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?

The description adds valuable behavioral context beyond annotations: authentication requirements, delivery caps, phone verification, and the fact that webhook signing secret is returned only once. It does not contradict the annotations (idempotentHint is ambiguous but not contradicted). This provides agents with important side-effect information.

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: it front-loads the core action, then prerequisites, then type-specific parameters, then delivery channels. It is comprehensive but could be slightly more concise, though the level of detail is appropriate 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?

Given the tool's complexity (3 parameters with nested objects, 5 subscription types, multiple delivery channels, no output schema), the description covers everything needed: purpose, parameter details, prerequisites, delivery options, and access to the persistent feed. It leaves no major 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?

With 100% schema coverage, the description adds substantial meaning by providing concrete examples for each subscription type (e.g., sec_8k with item codes, polymarket_edge with topics) and explaining delivery sub-parameters with specific formats and constraints (phone number E.164, email validation, webhook signing). This vastly extends 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 that the tool creates a proactive monitoring subscription to a live-data event stream and returns a new subscription ID. This specific verb+resource combination clearly distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides explicit prerequisites (Pipeworx OAuth account) and detailed guidance on delivery channel options with constraints (SMS cap, phone verification). It also mentions the always-on feed accessible via recent_alerts, offering implicit guidance on when to use alternatives. However, it does not explicitly state when not to use 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?

Annotations already provide readOnlyHint, idempotentHint, openWorldHint. Description adds that it returns category-bucketed example questions with tool shapes, and that calling with no arguments gives full spread. 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 trigger phrases and self-contained. Slightly long but each sentence adds value; could benefit from bullet points but still effective.

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

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

With only one optional parameter, no output schema, and annotations present, the description thoroughly covers purpose, usage, output content, and relationship to other tools. Agent has all necessary context.

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 schema already describes topic as optional focus area with examples. Description adds context by listing valid values and stating effect of omission ('cross-category spread'), exceeding baseline.

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

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

Description clearly states the tool provides example questions grouped by category, each with exact tool+argument shape. It identifies the tool as an onboarding entry point, distinguishing it 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?

Description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do' and explains when to pass a topic vs omit. It recommends using this before meta-tools, though does not explicitly state when not to use it.

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

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

Adds beyond annotations: ownership enforcement and deactivation behavior are stated. Annotations already indicate idempotent and non-destructive, and description confirms with 'deactivated not deleted'.

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, each essential: first describes action, second adds constraints and effect. 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?

Covers all necessary aspects for a single-parameter tool: what it does, ownership, idempotency, and data retention. References sibling tool 'recent_alerts' for completeness.

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 describes the 'id' parameter as a uuid from subscribe. Description adds no additional meaning, 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 verb 'Cancel' and resource 'subscription', and distinguishes it from siblings like 'subscribe' and 'list_subscriptions' by specifying the action of cancellation.

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 ownership is enforced, so users know they can only cancel their own subscriptions. It doesn't directly compare to alternatives but implies the right 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 indicate read-only, idempotent, non-destructive behavior. The description adds substantial context about return values (verdict types), the distinction between could_not_verify and unsupported, and the associated verification_error structure. It also warns explicitly that could_not_verify must not be treated as evidence, which is critical behavioral guidance 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 lengthy but well-structured, opening with example phrasings, then stating the use case, then detailing specific behaviors and return information. Each section serves a purpose; the length is justified by the tool's complexity. It is not overly verbose despite covering multiple paths and error semantics.

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?

Without an output schema, the description fully explains the return values (verdict options, citation, reasoning) and the error-handling semantics. It covers both routing paths, the meaning of each verdict, and the caveat about could_not_verify. For a tool with moderate complexity and no output schema, this description is highly complete.

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

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

The input schema already provides 100% parameter coverage with clear descriptions for both 'claim' and 'tolerance_pct'. The description adds minimal parameter-specific value; it references 'exact percent-delta math' in relation to tolerance but does not elaborate on how to set or interpret tolerance beyond the schema. Baseline 3 is appropriate given the schema's completeness.

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 names the tool's function ('validate claim', 'fact check', 'verify the claim that…') and specifies it verifies natural-language factual claims against authoritative sources. It also distinguishes itself from siblings by describing the fast path for company-financial claims and fallback for other claims, making it clear what this tool does that others do not.

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 states a clear usage trigger ('Use whenever the agent needs to check whether something a user said is factually correct') and explains the two routing paths (SEC/XBRL fast path vs grounded pipeline). It also notes it replaces multiple sequential calls. However, it does not explicitly list exclusions or alternative tools for subjective/non-factual queries, so it stops short of full when-not guidance.

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