Cms

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

Annotations already mark it as readOnly, openWorld, idempotent, non-destructive. Description adds valuable context: it probes LLMs, returns per-model data including raw responses, and clarifies that Anthropic calls require a BYO key. No contradiction with annotations.

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

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

Two sentences: first defines action and output, second adds optional details. Front-loaded with key purpose, then efficient expansion. No wasted words.

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

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

Given 4 parameters and no output schema, description covers return structure (per-model score, confidence, signals, raw_response + combined). It does not explicitly list all fields but provides enough context. Could be more detailed on output format.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds extra meaning: explains default model, that _apiKey is passed through to Anthropic, and that context disambiguates entities. This goes beyond the schema descriptions.

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

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

The description clearly states it probes LLMs for knowledge about an entity and scores visibility 0-100 per model. It specifies the default model and how to include additional ones. This distinguishes it from sibling tools like compare_entities or deep_research by focusing on AI visibility auditing.

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 mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains default model usage and BYO key for Anthropic. However, it does not explicitly state when not to use the tool or mention alternatives for comparing entities.

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 readOnly, openWorld, idempotent, and non-destructive. The description adds meaningful behavioral detail: it routes across 5,718 tools, fills arguments, returns 'structured answer with stable pipeworx:// citation URIs,' and is a 'one fast call' on every tier. This goes beyond annotations by informing the agent about routing behavior and output format. No contradiction found.

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

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

At roughly 180 words, the description is long, but every sentence carries routing, trigger-phrase, or alternative-tool information. It front-loads the key directive and uses examples efficiently. Slightly overpacked, but not padded or redundant — a 4.

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

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

The tool has a single required parameter and no output schema; the description covers when to use it, what it returns (structured answer with citation URIs), how it compares to siblings, and includes multiple concrete examples. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%; all six parameters are aliases for 'question' and are described in the schema. The description contributes example queries and natural-language trigger phrases, but the schema already documents the parameter semantics. Baseline 3 is appropriate since the description does not add essential parameter meaning beyond the schema.

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

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

The description opens with 'PREFER OVER WEB SEARCH...' and defines the specific action: 'Routes the question to the right one of 5,718 tools... returns the structured answer with stable pipeworx:// citation URIs.' This clearly distinguishes it from web search and sibling tools like ask_pipeworx_grounded and deep_research by specifying it as a routing/citation 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 states when to use: 'Use whenever the user asks...' and 'START HERE for most questions — this is the default entry point.' It gives distinct alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.' No ambiguity about when to choose this tool over 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?

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable dynamic context beyond that: no candidate is currently active, it matches ask_pipeworx exactly right now, and it is a full working router rather than a fallback stub.

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 and front-loaded: it immediately names the beta relation to ask_pipeworx, then provides the key behavioral facts in three sentences. The clarification that it is a full working router eliminates a likely misconception without padding.

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

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

For a one-question tool with a complete schema and strong annotations, the description covers identity, state, behavior, and usage guidance. It references the same response shape as ask_pipeworx, which gives the agent a path to understand the output even though no output schema is provided.

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

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

Schema description coverage is 100%, and the schema already documents the primary question parameter plus all five aliases with descriptions. The tool description adds no parameter-specific meaning, but the baseline of 3 is appropriate since the schema carries the full burden.

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

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

The description states exactly what the tool is: the beta version of the ask_pipeworx router, with the same 5,718 tools, same arguments, and same response shape. It clearly distinguishes it from the stable ask_pipeworx and the sibling ask_pipeworx_grounded by emphasizing it is the experimental edge.

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 it exactly like ask_pipeworx when you want the newest routing' and explains its results are compared against the stable router to decide what merges. This gives a clear selection criterion and identifies the alternative 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 the readOnly/idempotent annotations, the description discloses the exact success return shape, the explicit refusal mechanism, all refusal_reason enum values, the constraint that answers come only from tool results, and the cost of one extra LLM call. This is substantial behavioral context that annotations alone do not provide.

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

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

The description is dense and well-organized: purpose, mechanics, return contract, usage guidance, and cost tradeoff. It is longer than minimal, but every sentence contributes; the detailed return schema and refusal reasons earn their place. Slightly longer than ideal but not bloated.

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

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

The tool has no output schema, yet the description fully specifies the success and failure return shapes. It also explains routing behavior, refusal semantics, and the tradeoff with ask_pipeworx. An agent has everything needed to decide when to call it and 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?

Schema description coverage is 100%, including all six aliases for the single required parameter. The description does not add parameter-level semantics, but the schema already fully documents the natural-language question and its aliases, so the baseline of 3 is appropriate.

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

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

The description names a specific mode ('hallucination-resistant answer mode'), the resource ('Pipeworx'), and the core behavior: route, fetch, and extract the answer only from tool results. It also explicitly contrasts with the sibling ask_pipeworx, so an agent can distinguish it without opening the schema.

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

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

It gives explicit when-to-use guidance: high-stakes reads, quoted/cited/acted-on answers, financial verdicts, legal claims, medical lookups, public statements. It also states when NOT to use it: casual lookups should prefer ask_pipeworx because of the extra LLM call.

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, open-world. The description adds extensive behavioral context: market resolution, classification, fan-out to specific data sources, response structure (market, analysis, evidence), resolver contract with confidence levels and alternatives, parent event extraction, news fallback fields, low-confidence blocking, closed market handling, wide-spread warnings, and resolution-rule risk. 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 verbose but densely informative. It front-loads the core purpose and usage, then covers edge cases, response shapes, safety mechanisms, and resolution rules. Every sentence adds value, but some redundancy exists (e.g., repeated mention of closed markets). Overall, it earns its length through necessity.

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

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

Given the complexity (3 parameters, no output schema but detailed response documentation), the description is remarkably complete. It explains output structure (market, analysis, evidence fields), resolver contract, parent event extraction, news fallback behavior, safety guards (low-confidence, closed markets, wide spreads), and resolution-rule risk. It covers all essential context for correct invocation and interpretation.

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

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

Schema coverage is 100%, and the description adds significant value beyond schema definitions: it explains the market parameter's accepted formats (slug, URL, question text), the depth parameter's behavior (quick = 2-3 sources, thorough = full fan-out), and include_raw's impact on response size. Examples in schema reinforce usage.

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

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

The description clearly states the tool's purpose: researching a Polymarket bet by pulling Pipeworx data in one call. It specifies the inputs (slug, URL, question), the process (resolve, classify, fan-out), and output (evidence packet + comparison). It distinguishes from sibling tools like polymarket_arbitrage or polymarket_edges by targeting individual bet research.

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

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

The description 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 includes guidance on depth (quick vs thorough) and includes raw. However, it does not explicitly exclude cases where other tools would be better, though the sibling list implies 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds rich behavioral details: pulls latest 10-K data from SEC EDGAR/XBRL (handles off-calendar fiscal years), FAERS data for drugs, sorts results, returns citation URIs. 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?

Description is well-structured, starting with trigger patterns and purpose, then details. Each sentence adds value. Slightly verbose but efficient overall.

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, but description explains return format (paired data + citation URIs) and sorting. Covers both entity types with specific data sources. Complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with both parameters described. Description adds significant meaning: explains what data each enum value retrieves (company vs drug), provides examples for values, and clarifies constraints like max 5 items. Exceeds baseline 3.

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

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

Description clearly states the tool compares 2-5 entities (companies/drugs) in parallel. Uses specific trigger phrases like 'X vs Y', 'compare X and Y', etc., and distinguishes from 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 recommends preferring this over sequential lookups. Provides clear context for when to use (comparing entities) and examples for company and drug types, but lacks 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's behavioral contribution is limited to listing returned metadata fields. It is consistent but adds little 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 concise sentences, front-loaded with purpose, no wasted 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?

For a simple tool with one parameter and no output schema, the description adequately lists the metadata fields and provides usage context (post-search, pre-pull).

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 single parameter datasetId is 100% covered in the schema description. The tool description does not add extra meaning beyond 'Dataset UUID from search_datasets', which is already in 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 specifies the exact metadata returned (title, description, row count, etc.) and the resource type (CMS dataset), clearly distinguishing it from siblings like search_datasets (which lists datasets) and get_dataset (which retrieves rows).

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 ('after search_datasets') and what to do before pulling rows, providing direct context with a sibling tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description does not contradict them. It adds rich behavioral context beyond annotations: account/paid-plan requirements, parallel routing across 5,718 tools, the findings-packet shape (verbatim evidence, confidence, fetched_at, gaps[]), contradictions[], citation_uri fetchability, semantic excerpting, and latency expectations. No contradiction found.

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

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

The description is long but rarely wasteful; it front-loads the account prerequisite and the primary alternative before explaining the core behavior. Some redundancy with the schema's depth parameter definitions exists, but the extra latency and plan-cost details justify most of the length.

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

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

With no output schema, the description carries the full burden of explaining return behavior, and it does: findings packet fields, gaps[] for unanswered facets, contradictions[] for deeper depths, hop field, resolvable citation_uri semantics, excerpting behavior, and expected latency. It also covers authentication and a fallback path, making it complete for an agent deciding whether and how to call 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%, so the baseline is 3, but the description adds decision-relevant semantics not present in the schema: depth:'thorough' requires a paid plan, approximate latency per depth level, and why depth matters for multi-step questions (gap recovery vs. chasing leads). It reinforces the schema's enum meanings with practical operational 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 opens with a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1496 STRUCTURED data sources ... in ONE call.' It explicitly distinguishes itself from open-web search and names the sibling it is not (ask_pipeworx), making the tool's identity unmistakable.

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

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

Usage guidance is explicit and actionable: use for broad/multi-part structured-data questions, use ask_pipeworx for single lookups or breaking/current-news topics, and use ask_pipeworx if not signed in. It even names the alternative behavior for the excluded cases, leaving no ambiguity.

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

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

Annotations already indicate readOnly and idempotent. The description adds that it returns top-N tools with full schemas and examples, ready to call directly, and recommends calling it first, providing valuable behavioral context beyond annotations.

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

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

Two sentences: the first states purpose and output, the second gives usage guidance. Front-loaded with the verb 'Find tools', no wasted words.

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

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

Given no output schema, the description explains the output (top-N tools with schemas and examples) and usage context. It is complete for a discovery tool, covering what the agent needs to know.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds example usage and lists alias parameters, but the schema already covers parameter details, 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 finds tools by describing data or task, lists specific domains, and distinguishes itself as the tool to call first for exploration, differentiating from sibling tools.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set', providing clear context without exclusions.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds details about parallel calls across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), specific return fields, and limitations (patents soft-fail until May 2025). It does not contradict annotations.

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

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

The description is somewhat long but highly information-dense. It is front-loaded with example user intents and structured with bullet points. Every sentence adds value, but it could be slightly more 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?

Despite no output schema, the description thoroughly explains all return fields (cik, company_name, recent_filings with URIs, fundamentals sorted, patents, news, LEI) and notes relevant caveats (patent sunset, name requirement). This provides sufficient context for an agent to understand what the tool returns.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces that 'value' must be ticker or zero-padded CIK and adds practical guidance to use resolve_entity for names. This adds value beyond the schema but does not introduce new parameter semantics.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in one parallel call.' It includes specific example queries and distinguishes itself from siblings like resolve_entity by stating that names are not supported and that this tool should be preferred over chaining individual lookups.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides a 'when-not' condition: if only have a name, use resolve_entity first. This is clear guidance on when and when not to use the tool.

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

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

The description states deletion, which aligns with annotations (destructiveHint=true). It adds no new behavioral detail beyond the annotations, but is consistent and clear.

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, front-loaded with the core action. Every sentence serves a purpose.

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

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

Given the simple single-parameter input, annotations, and no output schema, the description covers all necessary operational context without overreach.

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

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

Schema coverage is 100% and the parameter key is well-described in the schema. The description adds no extra meaning beyond what the schema already 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 uses a specific verb-resource pair ('Delete a previously stored memory') and distinguishes itself 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?

Provides explicit usage scenarios ('context is stale, task is done, or clear sensitive data') and mentions companion tools, helping the agent decide when 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?

Annotations (readOnlyHint, idempotentHint, etc.) indicate safe read operation. The description adds that it fetches external pages and produces a text blob, which is not captured by annotations. No contradiction with annotations.

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

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

Three sentences, each purposeful: main function, process, use cases. No redundant information. Highly efficient.

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

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

For a simple tool with two params, no output schema, and comprehensive annotations, the description fully explains behavior and output. It addresses what the tool does, how, and why.

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 example values for url and default/max for max_links, but does not significantly extend beyond the schema. Acceptable.

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

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

The description clearly states the tool generates an llms.txt file for any URL, with specific verb 'generate', resource 'llms.txt file', and scope 'for any URL'. It details the process: fetches page, extracts title/description/key links, emits standard markdown. This distinguishes it from siblings like scan_competitor_ai_presence.

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

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

The description explicitly lists use cases: getting a client's site indexed, drafting for own project, auditing competitor. While it doesn't state when not to use or name alternatives, the context is helpful for deciding when to apply the tool.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral details: paging support, full-text search, and exact-match filter format, going 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 concise and front-loaded, with the main purpose in the first sentence. Every sentence adds value, and there is no redundancy or wasted words.

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

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

Given 5 parameters, no output schema, and the complexity of filters, the description fully covers usage: return format, paging, search, and filter syntax. It leaves no ambiguity for agents.

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 each parameter. The description adds meaning beyond the schema by explaining how filters map to returned row keys and providing examples.

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 rows from a CMS dataset by datasetId, using a specific verb and resource. It distinguishes from siblings by referencing search_datasets as the source for the UUID.

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

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

The description explicitly states the tool requires a datasetId from search_datasets, providing a clear prerequisite and context for use. It also explains when to use parameters like filters and keyword, though it doesn't explicitly list alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. Description adds return field details but does not significantly extend 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 with no wasted words: first states purpose and return fields, second gives usage guidance. Front-loaded and efficient.

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

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

For a simple tool with one optional parameter and no output schema, the description completely covers what it does, what it returns, and when to use it.

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

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

Schema description coverage is 100%, so the parameter is well-documented. Description only slightly reinforces parameter meaning, not adding substantial new semantics.

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

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

Clearly states the verb 'list' and resource 'subscriptions', and specifies returned fields. Distinguishes from siblings like subscribe and unsubscribe.

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

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

Explicitly says to use this tool to review monitoring before adding more subscriptions or to find an id to cancel, providing clear context and alternatives.

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

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

The description discloses substantive behavioral details beyond the annotations: rate-limiting ('5 per identifier per day'), cost semantics ('Free; doesn't count against your tool-call quota'), asynchronous feedback processing ('team reads digests daily'), and the claim_token mechanism for retrieving resolution status. It also explicitly warns not to paste end-user prompts, which is a valuable behavioral guardrail.

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

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

The description is front-loaded with a clear purpose statement, then covers usage, exclusions, token mechanics, and rate limits in an efficient, dense sequence. Every sentence contributes an actionable detail without redundancy; the length is justified by the tool's non-trivial 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?

Given the tool's complexity (4 parameters, nested context object, no output schema, claim_token follow-up mechanism), the description fully covers what the tool does, how to invoke it, what happens after filing, and the recovery path for checking status. It leaves no critical gaps for an agent to infer incorrectly.

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

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

Although the schema already covers all parameters (100% coverage), the description adds meaningful context not in the schema: that messages should describe issues in terms of Pipeworx tools/packs, not end-user prompts, and that claim_token is used to read replies to earlier reports. This goes beyond the schema's flat 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 specific verb ('Tell the Pipeworx team') and clearly enumerates the supported feedback types: bug, feature/data_gap, praise. It explicitly distinguishes this tool from siblings like ask_pipeworx by scoping it to feedback about Pipeworx tools only, not information retrieval.

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 for each feedback type ('Use when a tool returns wrong/stale data (bug)...'), and also a clear when-not-to-use exclusion ('if the tool came from a different MCP server... file it with that server instead'). It also explains the claim_token workflow, which acts as a usage alternative for those checking on prior feedback.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds that the signal is derived from CF analytics-engine, no PII, and cached 5min-1h. 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 informative but not overly long. Uses bullet points for use cases and additional details. Every sentence adds value.

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

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

Given one optional parameter, good annotations, and no output schema, the description explains the return (top tools, top packs, call volume) and caching. Adequate for a simple trending tool.

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

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

Only one parameter (window) with enum and description. The description adds context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' Adds value beyond the schema.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a window, with three specific use cases. It distinguishes itself from sibling tools like search or info tools by focusing on trending/recent demand.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical tool, aligning use case). Mentions window options and their effects. Does not explicitly state when not to use, but the guidance is clear.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true. The description adds substantial behavioral context: it walks child markets, checks date-axis/threshold-axis ordering, computes partition_sum, uses Jaccard similarity (≥0.30), filters placeholder slugs, and includes a fill check via polymarket_fill_risk. No annotation contradiction; description enhances transparency.

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

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

The description is comprehensive but slightly verbose. It is front-loaded with the main purpose, and every sentence contributes meaningful information. However, it could be more structured with bullet points for readability. Still, the density of useful information justifies a high 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, no output schema, and 27 sibling tools, the description is remarkably complete. It details all modes, algorithms, filters, and the fill check process. It even references another tool (polymarket_fill_risk) for custom sizing, covering edge cases thoroughly.

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 high value beyond schema: it explains the two parameters' purposes in detail, including examples, the difference between event and topic modes, and hints at response structure. This far exceeds baseline expectation.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It specifies distinct modes (trending_scan, event, topic) and differentiates from siblings like polymarket_edges and polymarket_fill_risk by detailing its unique algorithmic approach.

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

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

The description explicitly guides when to use each parameter: no args for trending_scan, `event` for specific market (recommended), and `topic` for cross-event scanning. It provides concrete examples (e.g., 'fed-decision-may-2026', 'Fed rate decision') and explains when not to trade (when fill check shows realizable_edge ≤ 0).

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

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

The description goes far beyond annotations by detailing caching (1h at KV level), response structure (by_segment, fed_candidates, _diagnostics), and edge calculation methodology. No contradictions with annotations are present.

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

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

The description is dense but well-structured with clear segments and front-loaded purpose. Every sentence adds value, though some details could be streamlined for a denser format.

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 9 parameters, no required parameters, and no output schema, the description is exceptionally complete. It explains response structure, caching, diagnostics, and compensates for missing output schema by detailing all response fields.

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 extra context for parameters like slippage_pp and min_liquidity (e.g., 'Bump for very thin partitions'), providing meaningful usage guidance 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 scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price. It differentiates from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on edge detection using specific model families.

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 it's built for 'what should I bet on today' and explains how agents can discover opportunities without paging. It provides guidance on using knobs but does not explicitly exclude alternatives or 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?

The description discloses behavioral traits beyond annotations: it explains read-only operations, data source (daily snapshots), response structure (tracked, expired, snapshot_dates), and limitations (60-day TTL, decay from daily closes). 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 detailed but well-structured, with a clear opening sentence, bullet-like explanation of response fields, and a limitations section. It is slightly verbose but earns its length by providing essential context.

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 provides comprehensive details about the response (tracked, expired, snapshot_dates) and limitations. For a tool with two optional parameters, this level of completeness is excellent.

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

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

Schema coverage is 100%, so the description adds value by clarifying defaults, constraints (days clamped 2-30, default 14), and the meaning of 'window' as snapshot family. It also explains the output structure, compensating for the lack of an output 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 explicitly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers specific questions about edge longevity and distinguishes itself from related tools like polymarket_edges by focusing on time-series analysis.

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

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

The description clearly indicates when to use the tool (e.g., to assess edge freshness) but does not explicitly state when not to use it or provide alternatives. The context is sufficient for an AI agent to understand its applicability.

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 true, destructiveHint false. The description adds behavioral details like 'walks the ladder and returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and a verdict' and notes that theoretical edge may not be capturable. 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 and packed but somewhat verbose. It front-loads the purpose and uses capitalization for emphasis. However, it could be more structured (e.g., bullet points for modes). The length is justified by complexity but could be tighter.

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

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

Given the tool's complexity (two modes, multiple return fields), the description is complete. It explains both modes, parameter behavior, return values (listed explicitly), and warns about risks. No output schema exists, so the description compensates well by detailing outputs.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds minimal extra context (e.g., default clamp 10-1e6, side default auto for basket) but mostly restates schema content. 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 states a specific purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market and basket) and explicitly links to sibling tools polymarket_arbitrage and polymarket_edges, avoiding ambiguity.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the risk of not using it (partial basket fills becoming unhedged directional positions), giving clear context for decision making.

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 richly discloses behavior beyond the read-only annotations: compatibility codes can be non-empty even when pairs are returned, unknown legs are never paired, pre-mapped topic pairs are flagged as unverified, and skipped comparison counters expose drops. This gives the agent a realistic model of the tool's conservative matching behavior.

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

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

The description is long but well organized with labeled sections for modes, response, safety fields, and codes, and it front-loads the core purpose. A few warnings are repeated in slightly different forms, which prevents a perfect conciseness 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?

Even without an output schema, the description covers the response shape, compatibility warnings and codes, unclassified-leg handling, temporal alignment, and skipped-pair counters. The agent has enough contextual information to invoke the tool and interpret its results safely and 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 baseline is 3; the description adds context by explaining that topic mode auto-fetches a pre-mapped event on each venue, explicit parameters are for custom pairings, and topic-mode results frequently warrant caution. It complements rather than merely repeats 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 opening sentence precisely identifies the tool's purpose: a cross-venue spread between Kalshi and Polymarket for the same resolving question. It also distinguishes this tool from single-venue Polymarket siblings by naming both venues and framing the output as a comparative spread with safety warnings.

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

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

The description clearly delineates the two modes—pre-mapped topic shortcuts versus explicit kalshi_event_ticker + polymarket_event_slug—and warns that pre-mapped topics are not necessarily tradeable. It does not explicitly name sibling alternatives or say when to choose this tool over, for example, polymarket_arbitrage, so it stops short of full 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, idempotentHint, destructiveHint. Description adds scoping detail ('anonymous IP, BYO key hash, or account ID') 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?

Three sentences, front-loaded with purpose, no filler. Every sentence adds value: purpose, use case, scoping, sibling pairing.

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 1 optional parameter and no output schema, description covers purpose, behavior, scoping, and relationship to siblings. Complete.

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

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

Schema covers the parameter with 100% coverage. Description adds behavioral nuance: omitting key lists all keys. This clarifies usage beyond schema.

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

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

The description clearly states it retrieves a value by key or lists all keys, distinguishing it from sibling tools remember and forget. The verb 'retrieve' and resource 'value previously saved via remember' are specific.

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

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

Explicitly says when to use: 'look up context the agent stored earlier' and contrasts with re-deriving. Provides context on scoping and pairing with remember/forget.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds behavioral detail about mark_read flag affecting next call and persistent feed nature, going beyond annotations.

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

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

Three sentences packed with essential information: purpose, returned data, filters, and behavioral notes. No redundancy, front-loaded with action verb.

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

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

With no output schema, description adequately describes returned fields and provides context for use cases (polls, alternative endpoint). Covers all aspects needed 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%, but description enriches each parameter with usage examples (e.g., 'sec_8k' for type, ISO timestamp for since) and explains behavior of mark_read and polling suitability.

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

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

Clearly states it pulls fired events from subscription feed, specifies returned fields (source, citation_uri, payload), and lists filtering options. Distinguishes from siblings by focusing on alert feed retrieval.

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

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

Provides context on when to use (Polls work fine) and mentions an alternative REST endpoint for scripts/dashboards. Lacks explicit when-not-to-use but gives sufficient guidance.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: parallel fan-out to multiple sources, GDELT→GNews fallback, USPTO PatentsView API sunset with soft-fail, accepted date formats with examples, and the output structure including pipeworx:// citation URIs. 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 front-loaded with user-facing query examples that immediately convey purpose. The technical details about sources and date formats follow logically. While fairly dense, every sentence adds value; no filler. Could be slightly shortened by removing the parenthetical about PatentsView, but acceptable.

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

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

Given the tool's complexity (multi-source, fallback, date parsing) and the absence of an output schema, the description covers the key inputs, sources, and output structure (changes[], total_changes, URIs). It doesn't detail error handling or pagination, but the annotations (idempotent, read-only) reduce risk. Adequate for effective use.

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

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

Schema coverage is 100%, so baseline 3. The description adds value by explaining the semantics of each parameter: 'since' accepts ISO date or relative shorthand with examples and a recommended default ('30d' or '1m'), 'type' is constrained to 'company', and 'value' can be ticker or CIK. This goes beyond the schema descriptions.

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

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

The description opens with concrete example queries ("What's new with X", "latest on Y") that make the tool's purpose immediately clear. It explicitly states it's a change feed for a company over a time window, lists the data sources (SEC EDGAR, GDELT→GNews, USPTO), and distinguishes itself from the sibling tool entity_profile.

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

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

The description gives explicit when-to-use guidance via the example query patterns. It also provides a direct when-not-to-use statement: 'Use entity_profile instead when you want the static profile regardless of window.' It explains the fallback behavior between GDELT and GNews, and mentions the USPTO soft-fail condition.

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

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

Annotations declare idempotentHint=true, readOnlyHint=false, destructiveHint=false. The description adds context about key-value scoping, persistence duration, and authentication differences. It does not contradict annotations and adds behavioral details beyond structured fields.

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

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

The description is well-structured with a clear opening sentence, use-case explanation, and scoping details. It is not overly verbose; every sentence adds value. Slightly longer than minimal, but still efficient.

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

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

Given two required parameters, no output schema, and comprehensive annotations, the description covers all necessary aspects: when to use, what to store, memory behavior, and sibling tools. It is complete for an agent to decide and invoke correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description provides examples and usage context but does not add semantic meaning beyond what the schema offers. 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 specifies the verb 'Save data' and the resource ('data the agent will need to reuse later'), provides concrete examples (resolved ticker, target address, etc.), and distinguishes from sibling tools recall and forget. It clearly states what the tool does.

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

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

Explicitly states when to use the tool ('when you discover something worth carrying forward') and what not to do (no alternative needed). Provides context on memory persistence (authenticated vs anonymous) and pairs it with recall and forget for retrieval and deletion.

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

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

The description goes well beyond the readOnly/idempotent/openWorld annotations by disclosing ambiguous-match behavior (returns figi_candidates rather than asserting), explicit unresolved fields, source labels on each identifier, and graceful degradation when GLEIF/OpenFIGI are unavailable. These are genuine behavioral facts an agent could not infer from annotations alone.

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

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

The content is front-loaded (trigger phrases and 'Use FIRST' come early) and nearly every clause carries decision-relevant detail. However, the company section is one massive nested-parenthetical paragraph with long run-on lists, which makes scanning harder than it needs to be; some bulletization 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?

With no output schema, the description carries the full burden of return semantics, and it does: it lists resolved identifiers per source, unresolved handling, figi_candidates on ambiguity, partial-failure behavior, and drug citation format. For a two-type, multi-backend resolver, nothing essential is missing.

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

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

Even with 100% schema coverage, the description adds significant value: it warns to pass the ENTITY NAME ONLY, gives a concrete counterexample ('NEW YORK ST DORM AUTH' rather than 'NEW YORK ST DORM AUTH revenue bonds'), and explains why (FIGI matches instrument names). It also clarifies which value forms are valid per type beyond the schema's short enum/label.

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 trigger queries and states the core action: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' SUPPORTED TYPES then enumerate exactly what is returned for company vs drug, making the purpose and scope unmistakable and distinct from sibling query/profile tools.

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

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

It gives explicit selection guidance ('Use FIRST whenever you have a name but need an ID') and clarifies broad accepted inputs (ticker, CIK, ISIN, brand/generic name), plus how it handles 'who owns X'/'is X a subsidiary of Y'. It never names sibling alternatives such as entity_profile or compare_entities or states when not to use them, so it stops short of full exclusion guidance.

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

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

Annotations already indicate safe, non-destructive, idempotent read. The description adds valuable behavior: probing each entity with ai_visibility_check, ranking by score, returning score/confidence/signal density, and treating first entity as subject. No contradiction with annotations.

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

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

Two sentences plus bullet point of return structure. Front-loaded with core action, then use case, then output summary. Every sentence earns its place with no redundancy.

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

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

With no output schema, description covers return structure (ranked list with score, confidence, signal density). Mentions special treatment of first entity. Could be more explicit about output format (e.g., list of objects with fields), but overall adequate given 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%, baseline 3. The description adds meaning beyond schema by explaining the purpose of 'context' (disambiguates common names) and the relationship between 'models' and '_apiKey'. This extra context elevates the score.

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, ranking them and identifying most/least recognized. It distinguishes from siblings like ai_visibility_check (single entity) by specifying multi-entity comparison.

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

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

The description provides a specific use case ('competitive AI-marketing audits') and an example question, but does not explicitly state when not to use or name alternatives. However, implicit differentiation from siblings like ai_visibility_check and compare_entities is present.

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 full safety profile (readOnly, openWorld, idempotent, not destructive). Description adds beyond: explains composite nature, timeout behavior (5-30s first measurement), graceful degradation with sources_failed field, and return structure details.

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

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

Every sentence earns its place. Front-loaded with composite nature and use case, then details return fields, limitations, and edge cases. 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 lacking output schema, description fully enumerates return fields (summary block, per-advisory detail, links, alternative versions). Covers input constraints, behavior, timeouts, partial failures. Complete for a 2-param tool.

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

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

Schema coverage is 100% and schema descriptions already define parameters well. Description adds minor context: scoped packages accepted, version defaults to latest. No additional semantics needed 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 composite 'should I add' check for npm packages, combining deps.dev and bundlephobia data. Specifies verb (scan), resource (dependency), and scope (npm). Distinguishes from siblings as no other tool does this composite analysis.

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

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

Explicitly says when to use: when agent asks about safety, popularity, size, or cost of adding a package. Also notes ecosystem limitation (NPM only) and points to alternative for other ecosystems via deps.dev directly. Mentions partial failure behavior.

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

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

Discloses that search is performed 'client-side over each dataset title/description/keywords' and returns a UUID (datasetId). Adds context beyond annotations (readOnly, idempotent), 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?

Four concise sentences, front-loaded with the core purpose. Each sentence adds value (catalog scope, search mechanism, usage guidance). 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?

No output schema, but description specifies return includes datasetId (UUID) and implies titles. Sufficient for an agent to understand the output shape, though exactly what fields are returned could be more explicit.

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. The main description adds the 'client-side' context but does not significantly enhance parameter meaning beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states the verb ('Find') and resource ('CMS dataset IDs + titles by keyword'). It distinguishes from siblings like 'get_dataset' by specifying that it returns dataset IDs to pass to downstream 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?

Tells the agent to pass the returned datasetId to 'get_dataset' and 'dataset_info', giving clear next steps. Lacks explicit when-not-to-use or comparisons with other search-like siblings, but the purpose is well-defined.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds embedding model details (BGE-base-en, cosine, 500-char windows), 200K char cap with truncation flag, and offset for verification. Adds significant value 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?

Description is front-loaded with the core action and is reasonably concise. Slightly lengthy but every sentence adds value. 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?

Covers use case, return type (passages with offsets and scores), truncation behavior, and pairing with sibling. No output schema, but description explains return values adequately. Minor gap: could clarify passage text format.

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

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

Schema coverage is 100% with descriptions for all three parameters. Description adds some context (e.g., examples for query, truncation for text) but not much beyond what schema provides. Baseline 3 is appropriate.

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

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

The description clearly states it performs semantic search inside a fetched record, with specific examples (SEC 10-K, article, long tool result). It distinguishes itself from sibling tools that fetch data or do other operations.

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 use when the record is too large for the prompt and pairs with ask_pipeworx_grounded. Does not explicitly state when not to use, but context is clear.

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

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

The description states 'Returns the new subscription id' implying non-idempotent creation, but the annotation sets idempotentHint=true. This contradiction undermines behavioral transparency, and no idempotency mechanism is described.

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

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

The description is front-loaded with purpose and then provides dense, valuable information. Slightly long but every sentence adds value; could benefit from bullet points for readability.

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

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

Given the complexity (multiple types, delivery channels, requirements), the description covers prerequisites, type examples, channel details, and constraints. Missing only output specifics beyond ID and idempotency clarification.

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

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

The schema has 100% coverage, but the description adds rich examples for each type, delivery constraints (SMS rate cap, phone verification, webhook HMAC details), and more precise parameter descriptions 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 creates a proactive monitoring subscription to a live-data event stream. It distinguishes itself from sibling tools like list_subscriptions (lists existing) and recent_alerts (pulls alerts) by focusing on creation.

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

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

The description provides clear context for use: proactive monitoring, requires Pipeworx OAuth account (excluding anonymous/BYO). It does not explicitly compare to siblings or state when to avoid, but the creation purpose is unambiguous.

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

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

The description adds significant context beyond annotations: it explains the tool returns example questions with exact tool+argument shapes, drawn from a live catalog of thousands of tools. It also details the behavior of no-argument vs topic-specific calls. No contradiction with annotations (readOnlyHint true, etc.).

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 one long but information-dense sentence. It front-loads the purpose with common user queries. However, it could be broken into clearer sections for readability. No wasted words.

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

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

Given no output schema, the description clearly explains what is returned: category-bucketed example questions with tool+argument shapes. It also covers the param behavior and use case thoroughly. No gaps for a discovery/onboarding tool.

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

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

The description adds meaning to the 'topic' parameter by listing concrete focus areas (e.g., 'finance', 'pharma', 'betting') and explaining that omitting the parameter gives a cross-category spread. Since schema coverage is 100%, the baseline is 3, and the description provides additional context, justifying a 4.

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

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

The description clearly states it is an onboarding entry point, returns category-bucketed example questions (e.g., 'company financials', 'drugs & clinical trials'), and helps the agent understand what Pipeworx is good for. It uses specific verbs like 'returns' and lists actionable categories, distinguishing it from sibling tools like ask_pipeworx or entity_profile.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains when to omit topic for a full spread or specify a topic for focus. It does not explicitly state when not to use it, but the context is clear.

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

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

Annotations indicate idempotent and not destructive; description adds that the row is deactivated, not deleted, preserving historical events, which is beyond 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?

Two concise sentences with no wasted words, front-loaded with the main action and key behavioral details.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers all essential aspects: purpose, ownership constraint, and effect on data.

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

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

Schema covers the single parameter with a description; description does not add extra meaning beyond what is in the schema, so baseline of 3 is appropriate.

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

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

The description clearly states the verb 'Cancel' and resource 'subscription', with additional details about ownership enforcement and deactivation vs. deletion, distinguishing it from sibling tools like 'subscribe' or 'list_subscriptions'.

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

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

Description explains when to use (cancel own subscription) and what happens (deactivated, not deleted), but does not explicitly state when not to use or compare to alternatives.

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

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

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), the description discloses crucial behavioral traits: the two distinct execution paths (SEC EDGAR fast path vs grounded pipeline), the meaning of each verdict, and especially the warning that could_not_verify means the check did not happen (verification_error) and must not be used as evidence. This goes far beyond the annotation hints and prevents misinvocation.

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

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

The description is longer than average but every sentence contributes: it opens with user-phrase triggers, defines the scope, explains routing, enumerates outputs, provides critical caller warnings, and ends with an efficiency justification. It is well-structured and front-loaded, with no filler or redundancy.

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

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

Even without an output schema, the description fully specifies what callers will receive: verdict enum, actual value with a pipeworx:// citation, reasoning, and error structure for could_not_verify. It also addresses edge cases (unsupported vs could_not_verify) and the two data-source paths. For a tool of this complexity, the description is exceptionally complete.

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

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

The schema already describes both parameters, and the description adds valuable context: the claim parameter examples show expected formats, and tolerance_pct is explained with its role in overriding the implied tolerance, a recommendation for hallucination detection, and its default (capped at 5). This exceeds the baseline for 100% schema coverage by adding operational guidance.

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

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

The description clearly states a specific verb ('verify') and resource ('natural-language claim verification against authoritative sources'). It provides concrete trigger phrases ('fact check', 'confirm or refute'), describes the two routing paths (SEC EDGAR + XBRL for company-financial claims, grounded pipeline for other claims), and lists the exact verdict values returned. This distinguishes it from sibling tools like ask_pipeworx_grounded or deep_research by focusing on claim adjudication with a defined outcome.

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 states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies the scope by distinguishing company-financial claims from any other factual claim and explains the fallback behavior. The note that it 'Replaces 4–6 sequential calls' gives a clear reason to prefer this tool over composing multiple primitive calls.

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