Ens

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description confirms these by describing probes and requiring API key for certain models. It mentions API calls and BYO key cost, but lacks details on rate limits or latency. 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 concise (5 sentences) and front-loaded with the core action and result. Every sentence adds unique value, covering purpose, default behavior, optional feature, return format, and use cases. 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, no output schema, and no nested objects, the description is thorough. It explains parameter usage, default behavior, and expected return per model. It covers multiple use cases and disambiguates the optional context field. Lacks explicit output structure but suffices.

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 all 4 parameters with descriptions. The tool description adds context (default model, API key purpose, context disambiguation) but does not significantly extend beyond what the schema already provides. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: probing LLMs for knowledge about an entity and scoring visibility. It specifies the default model, optional Anthropic probing, and return structure. It differentiates from siblings like scan_competitor_ai_presence by focusing on AI-marketing audits and brand visibility.

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 usage contexts (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use the optional API key. It lacks explicit when-not-to-use guidance or contrast with similar siblings, but otherwise gives sufficient direction.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, confirming safe read-only behavior. The description adds valuable behavioral context beyond that: the tool routes to specialized tools, fills argument values, and returns structured answers with stable pipeworx:// citation URIs. It does not contradict the annotations.

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

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

Despite being relatively long, the description is front-loaded with the critical directive 'PREFER OVER WEB SEARCH', followed by dense, useful detail: source domains, trigger phrases, concrete examples, and a 'START HERE' default. Every sentence adds practical value for an agent deciding whether to invoke this tool.

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

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

For a general-purpose router tool with no output schema, the description provides enough context to call it correctly: what inputs to provide, what kinds of questions are appropriate, and what the response will include (structured answer plus citation URIs). The list of examples and trigger phrases makes invocation decisions straightforward even without an output schema.

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

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

The schema description coverage is 100%, and the single meaningful parameter 'question' is fully documented, including aliases q, query, prompt, text, and input. The description adds no further parameter-level semantics, which is acceptable because the schema already carries the complete burden. Baseline 3 applies.

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

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

The description clearly identifies the tool as a general question-answering router: it 'routes the question to the right one of 5,714 tools' and 'returns the structured answer with stable pipeworx:// citation URIs.' It distinguishes itself from web search by explicitly preferring this tool for factual, data-backed queries, though it does not explicitly distinguish itself from the sibling ask_pipeworx_beta or ask_pipeworx_grounded tools.

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

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

The description gives strong, explicit usage guidance: a comprehensive list of data domains, trigger phrases like 'look up', 'find', 'get the latest', and examples such as 'current US unemployment rate' and 'Apple's latest 10-K'. It even says 'START HERE for most questions.' However, it does not provide explicit when-not-to-use conditions or name alternative sibling tools, so it falls just short of a 5.

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

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

With readOnly, idempotent, and non-destructive annotations already present, the description adds meaningful behavioral context: candidate routing improvements are enabled live only when one is under test, none is active now, and it currently matches ask_pipeworx exactly. It also clarifies the potential misconception with 'Falls back to nothing — this IS a full working router.'

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

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

The description is front-loaded with the core fact and each sentence contributes operational information such as current candidate status and usage instructions. Some specifics like '5,714 tools' and the exact retirement date are slightly heavy, but they support the parity claim.

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 an experimental twin of a known sibling, the description covers parity, current behavior, when to use it, and the no-fallback guarantee. It references 'same response shape' rather than detailing return values since no output schema is present, which is reasonable but less self-contained than ideal.

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 'question' and its aliases. The description only repeats that arguments are the same as ask_pipeworx, adding no per-parameter meaning beyond the schema, so the high-coverage baseline of 3 applies.

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

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

The description clearly names the tool as the 'Beta version of ask_pipeworx' and defines it as an identical universal router with the same 5,714 tools, arguments, and response shape. This distinguishes it from the stable ask_pipeworx sibling and avoids tautology.

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

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

The description explicitly tells the agent to 'Use it exactly like ask_pipeworx when you want the newest routing' and names the stable router as the comparison point for merges. It provides clear context but no explicit when-not-to-use exclusions, so it stops short of a 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the full refusal behavior, refusal_reason taxonomy, the guarantee to use only tool result content, and the exact success/refusal return shapes. It also notes the additional LLM call cost and the high-stakes framing.

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

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

The description is long but every sentence earns its place: core identity is front-loaded, followed by behavior, refusal modes, use cases, and cost trade-off. No filler or redundancy.

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

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

With no output schema, the description correctly takes on the burden of explaining return values and refusal modes. It also covers routing context, source scope, use cases, and the cost-vs-accuracy trade-off, making the definition complete for correct invocation.

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

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

Schema coverage is 100%, and all six parameters are aliases for the question parameter, so the schema fully documents them. The description adds context about routing and internal argument filling, but it does not add 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 states a specific purpose: a hallucination-resistant answer mode for high-stakes reads, with the same routing as ask_pipeworx but grounded extraction. This clearly distinguishes it from the sibling ask_pipeworx and explains exactly 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 it (answers will be quoted, cited, or acted on; must not invent facts) and when not to (prefer ask_pipeworx for casual lookups). It also discloses the extra cost of one LLM call, giving clear selection criteria.

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 extensively details behavior beyond annotations: resolution process, fan-out logic, safety mechanisms (low-confidence short-circuit, closed market status), illiquid market flags, cancellation rules, and news fallback. Annotations already indicate read-only and idempotent, but the description adds critical operational details.

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

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

The description is very long but well-structured with clear sections. Every sentence adds value, though some fan-out examples are verbose. It is front-loaded with purpose and usage, then dives into 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?

For a tool with 3 parameters and no output schema, the description covers all relevant aspects: input flexibility, depth options, include_raw behavior, classifier list, fan-out examples, response shapes (market, analysis, evidence), resolver contract, parent event extraction, news fallback, safety, illiquid markets, and cancellation rules. Nothing is left unclear.

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

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

Schema coverage is 100%, but the description adds significant value: market parameter accepts slug/URL/question text, depth explains quick vs thorough fan-out, include_raw details size trade-offs and use cases. This far 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?

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, with specific verb ('research') and resource ('Polymarket bet'). It distinguishes from sibling tools like ask_pipeworx (general query) and polymarket_arbitrage (specific analysis) by focusing on bet research with data fan-out.

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

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

The description explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides classifiers and fan-out examples to guide usage. It does not explicitly exclude non-bet questions, but the specificity makes it 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?

Discloses detailed behavioral traits beyond annotations: explains data sources for company (SEC EDGAR/XBRL with off-calendar handling) and drug (FAERS, FDA counts, trials), sorting behavior, and output format (paired data + 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?

Concise at ~150 words, front-loaded with examples. Every sentence serves a purpose (examples, usage preference, entity specifics, sorting, output). No unnecessary text.

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

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

Complete given the tool's simplicity (2 params, no output schema, rich annotations). Covers purpose, when to use, what each type returns, sorting, edge cases (off-calendar fiscal years), and 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 coverage is 100%, so baseline is 3. Description adds value by explaining the entity types, providing examples (tickers/CIKs for company, drug names), and noting max/min items. Enriches parameter understanding.

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

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

Description starts with concrete example queries and clearly states the action: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It distinguishes from siblings by explicitly recommending over sequential lookups and stating it replaces 8–15 calls.

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

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

Provides explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Includes example query patterns. Lacks explicit 'when not to use' but context is clear enough.

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

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

Even with readOnlyHint, openWorldHint, and idempotentHint annotations, the description adds substantial behavioral detail: sign-in requirements, thorough requiring a paid plan, parallel routing, findings packet fields, explicit gaps[] that are never invented, semantic excerpting of large records, and expected latency. It also explains depth-specific behaviors. 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 critical account requirements and alternative routing, and it is reasonably sized for the tool's complexity. However, it includes a nonsensical artifact at the end, 'Wait, then there's a strange section: "For a single lookup use ask_pipeworx instead..."', which repeats prior content and disrupts clarity, so not every sentence earns its place.

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

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

The description is complete for a complex tool with no output schema: it explains the research process, returned findings packet fields, gap handling, contradictions, depth modes, latency, authentication, and when to use an alternative. An agent has all needed information to decide and invoke the tool correctly.

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

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

The schema already covers both parameters with high detail, but the description adds meaning beyond the schema: depth:"thorough" requires a paid plan, and the sign-in state affects tool selection. This supplements the schema-level definitions with important 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 clearly states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1495 STRUCTURED data sources' in 'ONE call', decomposing the question into facets and routing to 5,714 tools in parallel. It also distinguishes itself from open-web search and names ask_pipeworx as the alternative for single lookups, so an agent can tell it apart from siblings.

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

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

It explicitly says when to use the tool: 'Best for broad/multi-part questions over structured data', and when not to: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx instead'. It also gives concrete examples, so selection guidance 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns top-N most relevant tools with full schemas and curated examples, ready to call directly. No contradictions.

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

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

Single paragraph, front-loaded with purpose, then examples, then return value and usage advice. Every sentence adds value; no waste.

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

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

Given high schema coverage, rich annotations, and no output schema needed, description fully covers purpose, usage, and return format. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context about query aliases and examples, but schema already documents all parameters; minimal added value beyond that.

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 'Find tools by describing the data or task', lists many example domains, and distinguishes from siblings by being a discovery tool. Verb + resource + scope 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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)', providing clear when-to-use context and implying when not to use.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description details return fields (cik, company_name, recent_filings with URIs, fundamentals sorted by period, patents with sunset note, news with fallback, LEI). It also mentions the patents soft-fail behavior, adding valuable behavioral context.

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

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

The description is concise and front-loaded with example queries, but it is a single run-on sentence that packs many details. While no information is missing, it could be slightly more structured 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?

Without an output schema, the description fully explains the return values (filings, fundamentals, patents, news, LEI) and covers edge cases (patents sunset, name not supported). It also justifies preferring this tool over chaining, making it complete for an AI agent.

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

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

Schema coverage is 100% and the description adds meaning beyond the schema, such as explaining that 'value' accepts ticker or CIK but not names, and that 'type' is limited to 'company'. This clarifies usage and prevents errors.

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 provides a full cross-source profile of a US public company using specific verbs like 'tell me about' and 'research'. It explicitly distinguishes from sibling tools like 'compare_entities' and 'resolve_entity' by noting it should be preferred over chaining single-source 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 specifies when to use (holistic view of a company) and when not to (if only a name is available, use resolve_entity first). It also provides exact input formats (ticker or zero-padded CIK) and lists the sources it fans out across.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds 'clear sensitive data' context but doesn't 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?

Two sentences, front-loaded with key action, no unnecessary words.

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

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

Simple tool with one parameter. Description, schema, and annotations fully cover what the tool does 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 has 100% coverage for the single parameter 'key' with description. Description does not add additional 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 clearly states the verb 'Delete', resource 'memory', and method 'by key'. It distinguishes from siblings by naming 'remember' and 'recall'.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data' and pairs with 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?

Discloses key behavioral traits: fetches the page, extracts title/description/key links, outputs standard markdown format. Complements annotations (readOnlyHint, idempotentHint) with concrete actions, without contradiction.

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

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

Two concise sentences followed by a bulleted list of use cases. Front-loaded with main 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?

Despite no output schema, the description clearly states the output is a single text blob ready to drop at site-root/llms.txt. Covers input, behavior, and output sufficiently for a simple tool with two parameters.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minimal meaning beyond schema—e.g., example URL format and default/max for max_links are already in schema fields.

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

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

Clearly states the tool generates a production-ready llms.txt file for any URL. Specifies the verb 'generate', resource 'llms.txt file', and context for AI crawlers. Distinguishes from sibling tools like 'ai_visibility_check' and 'scan_competitor_ai_presence' which focus on visibility analysis rather than file generation.

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

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

Provides explicit use cases: getting a client's site indexed, drafting for own project, auditing competitor. Offers context for when to use but does not explicitly state when not to use or name alternative tools, though siblings exist.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint). Description adds detail about return fields but no new behavioral traits 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, front-loaded with purpose and return fields, followed by usage guidance. 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?

Returns fields are listed despite no output schema. Parameter is simple. For a list tool, it is adequately complete; missing pagination details are acceptable.

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

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

Schema description coverage is 100%, so the schema already explains the single optional parameter. Description adds no additional 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 clearly states the verb 'List', the resource 'the caller's active subscriptions', and lists return fields, distinguishing it 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?

Explicit guidance is given: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It tells when to use, though no explicit exclusion of alternatives is provided.

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

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

Annotations are all false/neutral, so the description carries the burden. It richly discloses behavior: anonymous filing returns a claim_token for later status checks, rate limit of 5 per identifier per day, free (no quota), and daily human review. This goes well beyond the minimal annotations and contains no contradiction.

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

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

The description is long but every sentence adds value: purpose, use cases, exclusions, claim_token flow, rate limit, and roadmap impact. It is front-loaded with the primary purpose, but could be tightened slightly without losing information.

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

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

Given the tool's complexity (nested context object, zero required params, no output schema), the description covers all essentials: purpose, when-to-use, exclusions, return behavior (claim_token), rate limit, and next steps. It is complete enough for an agent to invoke correctly without additional context.

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

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

Schema already covers 100% of parameters with descriptions. The description adds practical semantics: instructs users to describe issues in terms of Pipeworx tools/packs (not paste end-user prompts) and explains the claim_token resurrection pattern. This enhances the schema without redundant repetition, though it does not add deep syntax details.

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

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

The description states a specific verb ('Tell') and resource ('the Pipeworx team'), and clearly defines the scope: reporting broken/missing/needed functionality. It distinguishes from siblings by explicitly limiting feedback to tools served by this Pipeworx connection and contrasting with filing for other MCP servers.

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

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

Provides explicit when-to-use criteria (bug, feature/data_gap, praise) and when-not-to-use (tools from other MCP servers, with advice to file there instead). Also gives a fallback ('Not sure? Pipeworx tool names are the ones this connection lists') to resolve 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds critical behavioral context: data is derived from CF analytics-engine, contains no PII, is cached for 5min-1h, and is self-aggregating. 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 tightly structured: a lead sentence summarizing output, three bullet-point use cases, and a closing note on data source and caching. Every sentence earns its place with no redundancy or fluff.

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

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

Despite lacking an output schema, the description fully explains return values ('top tools, top packs, total call volume', format as '(pack, tool, count)') and caching behavior. For a simple tool with one optional parameter, this is entirely sufficient.

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

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

Schema coverage is 100% for the single parameter (window). The description adds semantic value by explaining the effect of different window choices: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond the schema's enum listing.

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 recent window (24h, 7d, or 30d)'. It distinguishes from siblings like 'discover_tools' by focusing on real-time call activity from other AI agents, and lists specific use cases, making purpose unambiguous.

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

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

The description explicitly enumerates three use cases: discovering hot data sources, confirming canonical tool choice, and aligning use case with demand. While it does not mention when not to use the tool or alternative tools, the provided guidance is clear and actionable.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds significant behavioral context: how arbitrage detection works (monotonicity, partition checks), the fill check mechanism, semantic anchor threshold, placeholder filtering, and output structure. 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 efficient and well-structured, front-loading the main purpose and then detailing each mode. Every sentence adds necessary context without redundancy. The use of section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) improves readability.

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

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

Given the tool's complexity (three modes, edge cases, fill check logic), the description is remarkably complete. It covers input behavior, output structure, error handling (placeholder filter, low similarity), and references sibling tools. No output schema, but the description sufficiently describes the response 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?

Input schema has 2 optional parameters with descriptions. The description adds substantial value: explains event mode with examples, topic mode with seed questions, and cross-event behavior. It clarifies the difference between modes and adds context that the schema alone does not provide.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific use cases, making the purpose unambiguous.

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

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

The description provides explicit guidance on when to use each mode (no args for trending scan, event for specific market, topic for cross-event). It also references a sibling tool (polymarket_fill_risk) for custom sizing. However, it does not explicitly compare against other siblings like polymarket_edges or polymarket_edge_tracker, which could help an agent choose more precisely.

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 is exceptionally detailed about internal behavior, far beyond what annotations provide. It explains the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), the edge calculation (edge_pp_net, kelly_fraction), the diagnostics output, and even caching behavior ('Cached 1h at the KV level'). Annotations declare readOnlyHint, openWorldHint, idempotentHint as true, and the description aligns with these (no mutation, idempotent, open-world). No contradiction detected.

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

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

The description is long but well-structured: opening sentence defines purpose, followed by detailed segment descriptions, then response fields, then parameter knobs, then response structure. It is front-loaded with the most important information. However, the description could be slightly more concise by trimming some internal details (e.g., specific alpha values for sports). Still, it remains readable and informative.

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

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

The description is remarkably complete given the tool's complexity (9 parameters, no output schema, nested response). It explains the response top-level structure (by_segment, fed_candidates, _diagnostics), the meaning of edge_pp_net and kelly fields, and even the caching policy. It leaves no ambiguity about what the tool returns or how it behaves. The diagnostic counters help callers understand empty segments. This is exemplary contextual completeness.

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

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

With 100% schema description coverage, each parameter already has a clear definition. The tool description adds value by grouping parameters into 'Tradeable-edge knobs' and explaining their interplay (e.g., min_kelly vs min_partition_leg_kelly). It also provides context like slippage_pp defaults and when to adjust. This goes beyond the schema, hence a 4 rather than baseline 3.

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

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

The description explicitly states the tool's purpose: scanning Polymarket markets for opportunities where Pipeworx data disagrees with market price. It uses a specific verb ('scan') and resource ('Polymarket markets'), and clearly distinguishes from sibling tools like polymarket_arbitrage (which focuses on arbitrage) and polymarket_edge_tracker (which likely tracks edges over time). The description also identifies the target use case ('what should I bet on today'), making it clear when to use this tool.

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

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

The description is built around a clear use case ('what should I bet on today') and explains that the tool discovers opportunities without paging through hundreds of markets. It provides guidance on how to use knobs (min_liquidity, max_spread_pp, etc.) to filter opportunities. However, it does not explicitly state when not to use this tool or compare it with siblings like polymarket_arbitrage or bet_research. Still, the context is strong enough for an agent to make informed decisions.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description goes beyond by detailing response structure (tracked, expired arrays with fields like first_seen, trend, decay_pp_per_day), limits (60-day TTL), and interpretation notes (negative value = SELL YES). No contradiction.

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

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

The description is relatively long but every sentence adds value, covering purpose, response format, and constraints. It is front-loaded with the key question. Slightly verbose but justified by complexity.

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

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

Given the tool's complexity (time-series analysis, multiple output fields) and minimal schema (no output schema), the description provides thorough structural and behavioral details including arrays, fields, and edge cases (expired opportunities, gaps). Fully compensates for missing output schema.

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

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

Schema covers both parameters with descriptions. The description adds context about default and maximum values for 'days', and explains that 'window' refers to snapshot family with options. Since coverage is 100%, baseline is 3; the added nuance raises it to 4.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily polymarket_edges snapshots, distinguishing it from sibling tools like polymarket_edges (raw data) by focusing on time-series analysis and trend computation.

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

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

The description explains when to use the tool (to answer 'how long has this edge existed and is it shrinking?') and provides a motivational example differentiating fresh and aged edges. However, it does not explicitly state when not to use it versus alternatives.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details beyond annotations: it walks the order book ladder, returns a verdict (clean/degraded/cannot_fill), and describes basket risks including thin_legs and forced_directional_risk. No contradiction with annotations.

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

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

The description is well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) and front-loaded purpose. Every sentence adds value, but it is somewhat dense. Could be slightly more concise, but the structure makes it navigable.

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 complexity (multi-mode, no output schema), the description compensates by listing return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), covering single-market and basket behaviors, and providing usage guidance. It is self-contained and complete for an agent to decide when and how to invoke.

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% (all 4 parameters have descriptions). The description adds substantial meaning beyond the schema: for example, it explains how side defaults in basket mode (auto based on partition sum), and how size_usd is interpreted for buys vs sells vs basket. It provides detailed context that helps the agent correctly set parameters.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It includes specific verbs like 'check', 'walks the ladder', and 'returns', making the purpose unambiguous and differentiated from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly tells when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why (theoretical overround on thin books not capturable, partial fills cause unhedged positions) and mentions required parameters (one of market or event).

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

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

Annotations already declare the tool readOnly and idempotent, and the description adds substantial behavioral context beyond that: compatibility codes, skipped-pair counters, unclassified-leg exclusion, temporal alignment, and flags carried per spread entry. It also discloses the important quirk that both compatibility_warning and compatibility_codes can be non-empty even when matched_pairs > 0.

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 labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS), and every sentence carries operational meaning. The warning at the end is not filler; it sets accurate expectations about real-world usability. Given the tool's complexity and the absence of an output schema, the length is justified.

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

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

With no output schema, the description fully carries the burden of explaining return values, and it does so thoroughly: leg-by-leg prices, top_spreads_pp, compatibility fields, skipped_unclassified, low_confidence_pairs, temporal_alignment, and skip counters. An agent has enough to invoke the tool and interpret its result across all modes.

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%, yet the description still adds real value: it explains the relationship between the `topic` parameter and the two explicit override parameters, clarifies what 'overrides the topic-mapped side' means, and lists the exact shortcut values. This goes well beyond the baseline set by 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 a specific verb-resource pair: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes itself from same-venue tools like polymarket_arbitrage and polymarket_edges by emphasizing the cross-venue delta, and it names its two operating modes explicitly.

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 for both modes: use `topic` for 10 pre-mapped shortcuts and use explicit ticker/slug for custom pairings. It also warns that pre-mapped topics are often not tradeable and that compatibility warnings must be read even when pairs are returned, which is strong usage guidance.

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

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

Annotations already provide readOnlyHint=true and idempotentHint=true. The description adds value by noting scoping ('Scoped to your identifier') and pairing with remember/forget, but 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?

Two sentences with essential info, front-loaded with purpose. Could be slightly tighter but 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 a simple tool with one optional parameter, no output schema, and rich annotations, the description covers purpose, usage, scoping, and sibling relationships. Complete enough for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context: 'omit the key argument' to list all keys, which goes beyond the schema's 'omit to list all keys' (already in description field). The parameter is simple, and the description adds sufficient value.

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

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

The description states 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This is a specific verb+resource, and the mention of 'remember' and 'forget' as siblings differentiates it clearly.

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

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

Explicit guidance: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions pairing with 'remember' and 'forget', implying when to use alternatives. Examples such as 'user's target ticker' provide concrete context.

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

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

The description discloses that setting 'mark_read:true' flags returned events as read, modifying state. This contradicts the annotation 'readOnlyHint: true', which implies no state changes. The contradiction is a serious inconsistency.

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

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

The description is somewhat lengthy but well-structured, front-loading the purpose and covering return fields, parameters, and usage notes. Each sentence adds information, though some detail could be trimmed.

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

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

Despite no output schema, the description specifies return fields (source, citation_uri, raw event payload) and covers all parameters, polling behavior, and an alternative access method. No obvious gaps exist for this list-type tool.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds value by explaining 'since' requires ISO timestamp and elaborating on 'mark_read' behavior, enriching the schema's default explanations.

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

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

The description clearly states the tool retrieves fired events from a subscription feed, using specific verb 'Pull' and resource 'fired events'. It distinguishes itself from siblings like 'list_subscriptions' by focusing on events rather than 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?

The description mentions polling works and points to an alternative endpoint (alerts.json) for scripts/dashboards, providing some usage context. However, it does not explicitly contrast with sibling tools 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?

Annotations already indicate read-only, open-world, idempotent, and non-destructive. The description adds significant context: parallel fan-out to multiple sources, fallback from GDELT to GNews, soft-fail for USPTO, and return format with citation URIs. No contradictions.

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

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

The description is thorough and well-structured, starting with example queries, then listing sources, parameter details, and alternative tool. It is slightly long but every sentence carries meaningful information, earning a high score while allowing minor trimming.

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

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

For a complex tool with no output schema, the description covers all essential aspects: sources, fallback behavior, parameter formats, limitations (USPTO soft-fail), and return structure (changes grouped by source, total_changes, citation URIs). It is fully self-contained.

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

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

Schema coverage is 100%, but the description adds value beyond schema by explaining acceptable formats for `since` (ISO date or relative shorthand like '7d'), clarifying that `type` is currently limited to 'company', and expanding on `value` (ticker or zero-padded CIK).

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

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

The description clearly states the tool provides a change feed for a company over a specified window, listing specific sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishing itself from sibling tool entity_profile by noting when to use each.

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

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

Explicitly provides example queries, specifies that only 'company' type is supported, explains the `since` parameter format with examples, and tells the agent to use entity_profile for static profiles instead.

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

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

Annotations provide idempotentHint=true and destructiveHint=false, and the description adds key behavioral details: 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'. No contradictions. Additional context about scoping by identifier is helpful.

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

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

Four sentences that are front-loaded with purpose, then usage, then storage details. No fluff—every sentence adds value. Highly concise and well-structured.

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

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

Given the simplicity of the tool (2 required params, no output schema), the description covers purpose, usage, storage scope, persistence details, and sibling tool references. It is complete enough for an agent to use correctly. Minor omission: no mention of overwrite behavior or size limits, but these are implicit from idempotency.

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

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

Schema coverage is 100% with clear descriptions for both key and value. The description reinforces the key-value pair concept but does not add substantive new semantics beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse later, with specific examples like 'resolved ticker, target address, user preference'. It distinguishes from sibling tools recall and forget, making its unique purpose unambiguous.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward'. It also advises pairing with recall for retrieval and forget for deletion. While it lacks explicit when-not scenarios, the guidance is sufficient for typical use.

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

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

Annotations already indicate readOnly and idempotent. The description adds key behavioral context: 'Keyless' (no authentication required) and specifies the output fields (avatar, description, socials). This goes beyond what annotations provide.

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

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

The description is a single, well-structured sentence that front-loads the main purpose, lists key outputs, and includes the important 'keyless' detail. Zero waste.

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

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

Given the tool has only one parameter, no output schema, and rich annotations, the description provides sufficient context by listing the expected outputs. It covers the main use case and the 'keyless' trait. Could mention if it returns a raw address or formatted data, but overall complete.

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

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

Schema coverage is 100% and the parameter 'name' is well-described in the schema ('An ENS name, e.g. "nick.eth"'). The tool description does not add new meaning to the parameter, but the examples in the schema further clarify usage.

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

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

The description clearly states the action ('resolve') and the resource ('ENS name'), and explicitly lists the outputs ('Ethereum address and profile records'). It distinguishes itself from the sibling 'reverse_ens' by focusing on forward resolution, and from 'resolve_entity' by its ENS-specific nature.

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

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

The description implies the tool is for resolving ENS names, but it does not explicitly state when to use this tool over its siblings (e.g., 'reverse_ens' or 'resolve_entity'). No guidance on prerequisites or limitations.

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 substantial behavior beyond the readOnly/idempotent annotations: graceful degradation when GLEIF/OpenFIGI are unavailable, internal cascading through lookup endpoints, explicit handling of unresolved identifiers, ISIN-to-LEI mapping, and resolution of non-ticker instruments. No contradiction with annotations.

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

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

The description is dense and uses examples, labeled types, and clear behavioral notes, but the company type section is a long, heavily nested parenthetical that is harder to parse than the rest. It is still front-loaded and largely free of waste, so it earns 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?

There is no output schema, and the description compensates fully: it lists the returned identifiers (CIK, ticker, company_name, LEI, FIGI, RxCUI, ingredient, brand, citation), states unresolved-identifier behavior, covers ownership/subsidiary queries, and describes edge cases like non-US issuers and unavailable enrichment sources. 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 though schema coverage is 100%, the description adds critical operational meaning: for bonds pass the issuer name exactly as printed and never the full noun phrase, accept ticker/CIK/ISIN/name for company, and accept brand or generic for drug. This materially reduces misinvoation risk.

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

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

The description states a specific verb and resource: resolve a user-spoken NAME to the canonical/official identifiers other tools require. It opens with concrete natural-language examples and explicitly says 'Use FIRST whenever you have a name but need an ID,' which clearly distinguishes it from siblings like resolve_ens 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?

It gives a clear condition: use when you have a name but need an identifier, and it details per-type input handling (company, drug) and special cases like non-equity instruments. It does not explicitly name alternative tools or state when not to use it, so it stops short of a 5.

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

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

Annotations already provide safety profile (readOnly, idempotent, not destructive). Description adds 'keyless' indicating no authentication needed, and mentions returning profile records. 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?

Extremely concise: two sentences, front-loaded with verb and resource, 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?

Tool is simple with 1 param and known return type (ENS name + profile). Description covers the purpose but lacks specifics on return structure or error handling. Adequate given simplicity.

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

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

Single parameter 'address' has full schema coverage (100%) and clear description in schema. Description adds no new information beyond what schema provides.

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

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

Description specifies the verb 'reverse-resolve', the resource 'Ethereum address', and the result 'primary ENS name and profile records'. It clearly distinguishes from sibling 'resolve_ens' which likely does forward resolution.

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

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

Mentions 'keyless' as a potential advantage, but does not state when to use or when not to use this tool versus alternatives like resolve_ens or other tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds value by explaining the internal mechanism (probes with ai_visibility_check), ranking logic, output format (score, confidence, signal density), and treatment of the first entity as the subject. No contradictions.

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

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

The description is concise (~50 words), well-structured: purpose, mechanism, use case, and output. Every sentence is relevant with no wasted words.

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

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

Despite no output schema, the description fully explains the output (ranked list with score, confidence, signal density per entity). It covers the key behavior, parameter roles, and internal dependency (ai_visibility_check), making it complete for this tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minor nuance: the 'entities' first entry is treated as the subject, and 'models' defaults to workers-ai. This slightly enhances understanding but doesn't significantly surpass schema detail.

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

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

The description clearly states the tool's purpose: comparing AI visibility across multiple entities side-by-side, probing with ai_visibility_check, ranking, and surfacing most/least recognized. This distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (general 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 explicit context ('useful for competitive AI-marketing audits') and an example question. It implies the tool is for multiple entities but does not explicitly state when to use alternatives (e.g., use ai_visibility_check for a single entity).

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 safe read operations (readOnlyHint, destructiveHint false, idempotentHint). Description adds valuable behavioral context: composite one-call fan-out, partial failure handling, bundlephobia timing (5-30s), and sources_failed list. 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?

Well-structured and front-loaded with the composite nature and usage. Every sentence adds value, though slightly wordy. Could be tightened but remains effective.

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

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

No output schema, but description thoroughly explains return values (summary block with fields, advisories, links, alternative versions) and covers ecosystem, partial failures, and timing. Complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds meaning: scoped packages accepted, version defaults to latest, and provides examples. Adds value beyond schema.

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

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

The description clearly states the tool's function: a composite npm package check covering deps.dev and bundlephobia. It specifies the return summary block and distinguishes itself from siblings by its unique composite nature.

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

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

Explicitly states when to use: when an agent asks about safety, popularity, size, or cost of adding an npm package. Also notes ecosystem scope (npm only in v1) and fallback instructions for other ecosystems.

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

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

Annotations already indicate safe, idempotent, open-world, non-destructive. Description adds specifics: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char limit with truncation flag, and return of character offsets. 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?

Single paragraph with efficient, front-loaded content. Slightly dense but minimal waste. Could use more structure (e.g., bullet points for details) but still very 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?

Explains return values (passages with offsets and scores) even though no output schema. Covers limitations (200K char cap, truncation flag). Lacks detailed pagination or error handling, but adequate for the complexity.

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

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

Schema coverage is 100%, so base is 3. Description adds example queries for the query parameter and restates limits for text and limit, adding marginal 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 'Semantic search INSIDE a fetched record,' with a specific verb (search inside) and resource (fetched record). It distinguishes from sibling tools like ask_pipeworx_grounded by explaining the complementary use case.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded, 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 provides extensive behavioral details beyond annotations: it explains idempotency context (returning subscription id), restrictions (anonymous/BYO cannot persist), rate limits (10/day SMS), webhook signing, and auto-disable after failures. 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 front-loaded with the core purpose and efficiently covers complex details. While slightly long, every sentence adds value, and the structure (starting with summary then expanding on types and delivery) is logical.

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

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

Given the tool's complexity (multiple types, delivery channels, constraints), the description covers all necessary aspects: supported types, required auth, parameter examples, delivery options with constraints, and return value. No output schema exists, but the return is stated clearly.

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 significant value by detailing the nested 'params' object for each type and explaining delivery options with examples, thus aiding correct parameter construction.

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 ('subscribe') and describes the resource ('proactive monitoring subscription to a live-data event stream'). It clearly distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe'.

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

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

The description provides clear context on when to use this tool, including prerequisites (Pipeworx OAuth account) and specific subscription types with example parameters. It does not explicitly state when not to use it or direct to alternatives, but the sibling list and implicit guidance are sufficient.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's disclosure of returns (live tool shapes, category buckets) adds useful context without redundancy. The description also notes that the output is drawn from a live catalog, implying up-to-date results.

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, front-loading alternative phrasings and the tool's role. It lists categories in both description and schema, which is slightly redundant but not overly verbose. Each sentence serves a purpose: introduction, output description, usage instructions, and when-to-use guidance.

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 an onboarding tool with rich annotations and a fully described schema, the description is complete. It explains the output format, the effect of the optional parameter, and the tool's place in the workflow (first step). No output schema is needed given the straightforward return pattern.

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 fully covers the parameter with 100% description coverage, listing enum values. The description adds value by showing usage patterns (omit for full spread, pass a topic to focus) and providing illustrative examples like 'finance', 'pharma', which reinforce the schema's enum list.

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: returning category-bucketed example questions with exact tool call shapes. It differentiates from sibling tools like ask_pipeworx by positioning itself as the onboarding entry point to discover what to ask. The alternative phrasings ('what can I ask Pipeworx?', 'give me ideas') further clarify intent.

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?

Clear guidance is provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This sets expectations for when to invoke the tool versus query tools. It also explains how to use the topic parameter to narrow focus.

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

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

Beyond annotations (destructiveHint=false, idempotentHint=true), the description adds that 'the row is deactivated (not deleted) so its historical events stay available via recent_alerts,' clarifying post-invocation effects. 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, both front-loaded with key information (action and constraint). Every sentence adds value; no extraneous text.

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

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

For a simple one-parameter tool with no output schema, the description covers purpose, ownership, and impact on historical data via sibling 'recent_alerts.' Could mention error handling for invalid IDs, but overall comprehensive.

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 meaningful context by linking the 'id' parameter to 'subscription id (uuid) returned by subscribe,' enhancing understanding beyond the schema's minimal description.

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

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

The description clearly states 'Cancel a subscription by id,' specifying the verb 'cancel' and resource 'subscription,' with the unique constraint 'by id.' This differentiates it from sibling tools like 'subscribe' and 'list_subscriptions.'

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

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

The description includes ownership enforcement ('you can only cancel your own subscriptions'), providing explicit context for when the tool is applicable. It does not list alternatives or when-not conditions, but the constraint is clearly stated.

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

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

With readOnlyHint=true and idempotentHint=true already set, the description goes far beyond annotations by explaining the verdict types (confirmed, refuted, etc.), the critical distinction between could_not_verify (check did not happen) and unsupported (no source found), and the warning that could_not_verify must not be shown as evidence. It also describes the data routing and evidence citation, adding substantial behavioral context consistent with the annotations.

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

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

The description is front-loaded with examples and purpose, then methodically covers routing, return values, and failure semantics. Every sentence earns its place, but the trigger-phrase list is somewhat verbose and could be trimmed without losing meaning. Overall, it is well-structured and appropriately sized for the tool's complexity.

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

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

This is a complex tool with no output schema, yet the description fully prepares the agent: it specifies the verdict set, the grounded/structured actual value with citation, the meaning of could_not_verify and unsupported, the data-source fast path, and the efficiency benefit. There are no significant gaps in what an agent needs to know to invoke the tool and interpret its response.

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

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

Even though schema coverage is 100%, the description adds valuable guidance on tolerance_pct: explains how it overrides claim wording, gives a concrete use case (1–2 for hallucination detection), and states the default capped at 5. It also provides realistic claim examples for the required claim parameter, enriching meaning well beyond the schema's dry field descriptions.

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

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

The description clearly identifies the tool as natural-language claim verification against authoritative sources, using specific trigger phrases like 'fact check' and 'verify the claim that'. It distinguishes itself from general Q&A tools by focusing on factual correctness and mentions the two processing paths (SEC EDGAR fast path vs grounded pipeline), making its purpose unambiguous and differentiated from siblings.

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

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

The description states 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the routing logic for company-financial vs other claims. However, it does not explicitly name alternative tools (e.g., ask_pipeworx) or state when not to use this tool, so it lacks the 'when-not/alternatives' specificity needed for a 5.

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