Internet Archive

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

Annotations already declare readOnly/openWorld/idempotent, so the bar is lowered; the description adds real behavioral context: the default model is free, using Anthropic requires a BYO API key and direct payment, and it discloses the return shape (per-model score/confidence/signals/raw_response + combined view). This goes beyond the annotations without contradicting them.

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

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

Two sentences plus a use-case clause, front-loaded with the core action. No filler, every sentence contributes (action, default model/cost, return structure, use cases).

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

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

Despite lacking an output schema, the description compensates by listing the return fields and positioning. It covers models, API key requirements, and use cases. The only slight gap is the vague 'combined view' and no example invocation, but overall it's sufficiently complete for a moderate-complexity 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 each parameter already descriptively documented (e.g., _apiKey explicitly tied to the 'anthropic' model option). The description adds marginal context about default model and cost, but doesn't change parameter semantics, so 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 opens with a specific verb ('Probe') and clearly states the resource (LLMs) and outcome (score visibility 0-100 per model). It distinguishes from siblings like ask_pipeworx or scan_competitor_ai_presence by focusing on multi-model visibility scoring.

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 lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model and optional Anthropic key, giving clear context for when to use it. It doesn't name alternatives or exclusions, but the intended scenarios are adequately conveyed.

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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description reveals additional behavior: routes to one of many tools, fills arguments, returns stable pipeworx:// citation URIs, works on every tier, and makes one fast call. It does not discuss limitations, errors, or rate limits, but the disclosed routing and citation behavior adds meaningful 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 front-loaded with the crucial 'PREFER OVER WEB SEARCH' directive and is well-structured with examples and escalation paths. It is somewhat long, but each section serves a purpose—usage, alternatives, examples, and scope—so 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?

For a tool with a single required parameter and strong annotations, the description is exceptionally complete. It covers scope, use cases, examples, alternatives, output shape (citation URIs), and performance characteristics ('one fast call'). No output schema exists, but the description sufficiently explains what the user will get.

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

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

Schema coverage is 100%, with all parameters documented as aliases for 'question'. The description reinforces the natural-language nature and gives examples, but adds no new parameter-level semantics beyond what the schema already states. The baseline of 3 is appropriate because the schema handles the burden.

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

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

The description clearly identifies the tool as a question-answering router that selects among 5,529 tools across 1,455 verified sources and returns structured answers with citation URIs. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives for different needs.

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

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

Provides explicit when-to-use guidance: prefer over web search for factual questions, 'start here' for most questions, and step up to ask_pipeworx_grounded for hallucination-resistant answers or deep_research for broad/multi-part questions. Includes concrete example queries and even addresses breaking-news use cases.

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

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

The description goes beyond the readOnlyHint/openWorldHint/idempotentHint annotations by disclosing its experimental nature: candidate routing improvements are enabled live when under test, none are active currently, and it does not fall back to anything—it is a working router. This adds valuable context about potential behavior changes and testing procedures.

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

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

The description is four sentences, each with a distinct purpose: defining the beta status, stating the current inactive candidate state, providing usage instructions, and clarifying it is a full working router. It is front-loaded and contains no redundant restatement of annotations or schema 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?

The description adequately covers purpose, usage, and behavioral status. It references 'same response shape' to address the lack of an output schema, but does not explicitly enumerate what a response contains. Given that this is a variant of ask_pipeworx and siblings are listed, the description is sufficiently complete for the agent to use correctly.

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

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

The input schema documents all six parameters with 100% coverage, including 'question' and its aliases. The description mentions 'same arguments' as ask_pipeworx but adds no additional semantic detail about parameter formats, constraints, or examples. The schema already carries the load, so a baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx and states that it is an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes it from the stable ask_pipeworx by emphasizing the experimental edge. However, it does not explicitly state the primary verb action (e.g., 'routes your question'), relying instead on the name and sibling context.

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 an explicit usage directive: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that results are compared against the stable router to decide what merges, implying stable ask_pipeworx as the alternative. This clearly differentiates when to select this variant over siblings.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the refusal mechanism, possible refusal reasons, and the fact that it only uses tool results as evidence. It also reveals the cost tradeoff of one extra LLM call, which is valuable behavioral information.

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

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

The description is dense but every sentence carries information: mode, mechanism, return shape, refusal reasons, usage contexts, and cost tradeoff. It is front-loaded with the key differentiator and avoids 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?

Despite lacking an output schema, the description explicitly lists the success and refusal return structures. Combined with annotations and sibling context, the agent has all necessary information to 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 input schema already fully documents the single required parameter with aliases, achieving 100% coverage. The description adds no parameter-specific semantics beyond appropriate question contexts, which is more usage guidance than parameter meaning. Therefore, baseline 3 is appropriate.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' clearly defining the tool's core purpose. It explicitly contrasts with ask_pipeworx via 'Same routing as ask_pipeworx' while adding the grounded extraction distinction, so it is well distinguished from sibling tools.

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

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

It provides explicit guidance: use when answers will be quoted/cited/acted upon, and gives concrete domains (financial verdicts, legal claims, etc.). It also states when NOT to use it: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost.

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

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

Beyond the readOnly/openWorld/idempotent hints, the description discloses resolver confidence semantics, low-confidence short-circuiting, closed-market status, illiquid wide-spread flags, and resolution-rule risk (e.g., refund_50_50). These are non-obvious behaviors an agent must know, adding significant value beyond annotations.

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

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

The description is long but well-structured with clear uppercase section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESOLVER CONTRACT, etc.), and the first sentence gives the core purpose. It is dense with important details, though slightly overlong; a 4 reflects that it's not maximally concise but is organized.

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

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

For a tool with no output schema, this description covers input formats, response shapes (market, analysis, evidence), resolver contract fields, parent-event extractor, news fields, safety statuses, and cancellation rules. It leaves little to guess and includes concrete fan-out examples, making it complete 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?

All three parameters are fully documented in the schema (100% coverage), and the description largely mirrors the schema for 'market' without adding new parameter-level detail. The fan-out examples illustrate behavior but don't clarify parameter syntax/format beyond what's already in schema, so baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource ('Research a Polymarket bet by pulling the relevant Pipeworx data') and immediately clarifies input forms and target use cases. It distinguishes from siblings by focusing on one-call market research with fan-out evidence, not just pricing or alerts.

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

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

It explicitly says 'Use for "should I bet on X"...' and provides concrete query examples, establishing when the tool is appropriate. It doesn't explicitly name alternatives or when-not-to-use, so it loses the top score.

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 readOnlyHint/idempotentHint annotations, the description discloses data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), correct handling of off-calendar fiscal years, sorting by primary metric, and return format with citation URIs. This is substantial behavioral context beyond the annotations.

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

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

The description is front-loaded with trigger phrases and the core purpose. Every sentence provides necessary details, such as data sources, edge cases, sorting behavior, and return format. It is dense but not redundant, with no filler.

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

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

Though there is no output schema, the description explicitly states the return value (paired data + citation URIs), covers both entity types, and explains the sorting and fiscal-year handling. For a 2-parameter tool, this description fully covers all necessary context.

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

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

Schema coverage is 100% with descriptions for both parameters, so baseline is 3. The description adds valuable semantics by explaining what each type ('company' vs 'drug') pulls and how the values array is constrained to 2–5 entities, enriching the schema information.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs, with specific trigger phrases. It distinguishes from entity_profile by explicitly saying it should be preferred over sequential single-pack lookups and that it replaces 8–15 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?

Describes exactly when to use: when user asks for comparisons, rankings, 'X vs Y', etc. It explicitly says to always prefer this over sequential single-entity lookups when comparing, and provides type-specific data pull expectations, making usage context 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?

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals specific behaviors: account/paid-tier requirements, parallel decomposition across 5,529 tools, explicit gaps[] for unanswered facets, 'never invented' guarantee, contradictions[] scanning, semantic excerpting of large records, time expectations, and resolvable pipeworx:// citations. No contradictions with annotations are present.

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

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

The description is appropriately detailed for the tool's complexity and front-loads the critical account/tier caveat before the core functionality. Every sentence contributes meaningful information (purpose, alternatives, behavior, timing, citations). However, the structure is a single dense block of text; paragraph breaks would improve readability without losing content.

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

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

With no output schema, the description fully explains the return format (findings packet, gaps[], contradictions[], hop field, citation_uri), behavioral expectations (parallel routing, excerpting, never inventing), and operational constraints (account, time, depth variations). It also covers edge-case guidance for news topics. This is more than sufficient for a tool of this 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?

The input schema already provides detailed descriptions for both question and depth (including enum explanations), so the baseline is 3. The description adds value by explaining the practical implications of depth (hop count, gap recovery, contradictions, time) and clarifying that broad/multi-part questions are acceptable. However, much of this is partially repeated from the schema, so it does not fully transcend the structured data.

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 ('research') and clearly defines the resource ('Pipeworx's 1455 STRUCTURED data sources'), immediately distinguishing it from open-web search and sibling tools. It details a concrete output ('findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation') and contrasts with ask_pipeworx, making the tool's role unmistakable.

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

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

The description explicitly states when to prefer this tool ('best for broad/multi-part questions over structured data') and when to use alternatives ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). It also mentions account requirements and directs unsigned users to ask_pipeworx, providing complete use-vs-alternative guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable context by stating it returns 'top-N most relevant tools with names, descriptions, and full input schemas' and that results are 'ready to call directly, no second schema lookup needed.' This goes beyond annotations without contradicting them.

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

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

The description is three sentences, front-loaded with a clear purpose. The long list of data domains is arguably extensive but serves to clarify scope and aid matching. Each sentence contributes essential information (purpose, output, usage), so it is not unnecessarily verbose.

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

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

Despite no output schema, the description fully explains what the tool returns ('names, descriptions, and full input schemas') and when to use it ('Call this FIRST'). Annotations cover the safety aspects. For a read-only discovery tool, this is complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, with all parameters described including aliases. The description mentions 'top-N' and 'limit' conceptually but does not add syntax or default details beyond the schema. Since the schema already documents parameters well, the description adds no significant extra parameter semantics, hence the baseline score of 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's purpose: 'Find tools by describing the data or task.' It identifies the resource (tools) and scope (browse/search/look up for various domains). It distinguishes itself from siblings by positioning as a meta-tool for discovery, explicitly saying 'Call this FIRST when you have many tools available.'

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 usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It does not mention alternatives or exclusions, but clearly places itself as the initial discovery step, which is sufficient guidance.

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

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

The description goes well beyond the readOnly/idempotent annotations by disclosing the parallel fan-out across SEC, XBRL, USPTO, news, and GLEIF; specific return fields; the patents API sunset and soft-fail behavior; and the GDELT→GNews fallback. This is rich behavioral context that helps the agent anticipate side effects and failure modes.

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

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

The description is long but information-dense: it front-loads query examples, states the core intent in one sentence, then systematically lists outputs and constraints. Every sentence adds value, though it could be slightly tightened to improve scannability.

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 multi-source tool with no output schema, the description comprehensively covers input requirements, output structure, data source behavior, and edge cases (patent soft-fail, news fallback). No critical invocation-relevant information is missing.

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

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

Schema coverage is 100%, with both 'type' and 'value' already described in the schema. The description adds example formats ('AAPL', '0000320193') and reiterates the no-names constraint, which provides marginal reinforcement but does not significantly enhance the schema semantics.

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

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

The description clearly states it creates a 'full cross-source profile of a US public company in ONE parallel call', with specific examples of user queries. It also distinguishes itself from sibling tools by explicitly noting it should be preferred over chaining single-pack lookups, making its purpose and scope unmistakable.

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

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

Provides explicit when-to-use guidance ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view') and clear when-not-to-use ('names not supported — use resolve_entity first'). It also covers input format requirements, giving the agent a complete decision framework.

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 include destructiveHint=true and idempotentHint=true. The description adds context that the data is agent-saved and useful for clearing sensitive data, which goes beyond the annotations.

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

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

Two sentences with no redundancy. Action is front-loaded and the additional usage guidance is concise and purposeful.

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 single-parameter tool with robust annotations, the description sufficiently covers purpose, timing, and relationship to other tools. It could mention behavior on missing keys, but idempotentHint and schema already imply that.

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

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

Schema covers 100% of parameter information with the key description. The description merely restates that the key is used for deletion, adding no extra 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 action (delete), the resource (previously stored memory), and the method (by key). It differentiates from siblings like remember and recall by specifying deletion rather than storage or retrieval.

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

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

Provides explicit usage conditions: when context is stale, task is done, or clearing sensitive data. It does not state when-not-to-use or alternatives, but pairing with remember and recall gives contextual relationship.

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

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

Annotations already declare readOnly/openWorld/idempotent hints. The description adds behavioral context by stating it fetches the page, extracts title/description/key links, and emits standard markdown. This goes beyond the structured annotations without contradicting them.

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

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

The description is two sentences, front-loaded with the action and purpose, and includes use cases without unnecessary verbosity. Every sentence contributes to understanding the 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 simple generation tool with full schema coverage and clear annotations, the description covers input ('any URL'), process ('fetches, extracts, emits'), output ('single text blob'), and use cases. No critical information is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description only indirectly references the 'url' parameter and doesn't add detail on 'max_links'. The schema already fully describes both parameters, so the description adds little extra semantic 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 uses a specific verb ('Generate') and resource ('llms.txt file') with clear scope ('for any URL'). It explains the purpose (AI crawler indexing) and distinguishes the tool from siblings by its unique output format.

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

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

The description lists concrete use cases (client site indexing, personal project drafting, competitor auditing) giving clear context on when to use it. However, it doesn't explicitly mention alternative tools or exclusions, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint and destructiveHint, so the safety profile is known. The description adds value by specifying the return fields (id, type, params, etc.) and the default active-only behavior, which goes beyond the annotations. It does not contradict annotations.

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

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

The description is two sentences, front-loaded with the action and resource, then immediately the return fields and usage context. Every sentence earns its place with no filler or redundancy.

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

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

There is no output schema, so the description compensates by listing the return fields. The tool is a simple list operation with one optional parameter, and the description covers the purpose, usage, return value, and default filtering, making it fully complete for the agent.

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

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

Schema description coverage is 100%, and the include_inactive parameter is already well-documented in the schema. The description does not add additional semantic detail about the parameter beyond what the schema provides, so the baseline score 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 uses a specific verb ('List') and resource ('the caller's active subscriptions'), and explicitly distinguishes this from sibling tools like subscribe and unsubscribe by stating which operation context it serves. It also lists the exact return fields, making the purpose unmistakable.

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

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

The description explicitly states when to use this tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives clear contextual usage that implicitly contrasts with subscribe and unsubscribe, providing both a when and a why.

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

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

Despite annotations providing no hints (all false), the description discloses substantial behavioral details: rate-limited to 5 per identifier per day, free, does not count against tool-call quota, returns a claim_token for later status checks, and team reads digests daily. It also clarifies that the claim_token workflow requires passing it back with no other arguments. This goes far beyond the annotation surface.

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. It is front-loaded with purpose, then usage conditions, exclusions, message formatting guidance, claim_token workflow, and operational limits. No filler or redundancy; the structure flows logically from 'what' to 'when' to 'how' to 'caveats.'

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 4 parameters, a nested context object, no output schema, and minimal annotations, the description covers everything needed: use cases, exclusions, message format, claim_token retry workflow, rate limits, cost, and what the team does with feedback. It even anticipates ambiguity about non-Pipeworx tools. This is as complete as one could expect.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful parameter-level semantics: for claim_token it explains the exact workflow ('pass the pwfb_… token that filing returned, with no other arguments'), and for message it advises 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' While the schema already documents each parameter, the description enriches them with pragmatic usage context.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It lists concrete use cases (bug, feature/data_gap, praise) and clearly distinguishes itself from sibling tools by framing it as feedback about Pipeworx tools specifically, not a general query or action 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 explicitly states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives an explicit exclusion: 'ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead.' This is exemplary when/when-not 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 cover read-only, idempotent, and non-destructive behavior. The description adds valuable context: it is 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window.' This discloses data provenance, privacy, and freshness 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 well-organized: opening sentence states the core purpose, followed by a numbered list of use cases, then technical detail. Though the use-case list is slightly lengthy, every sentence earns its place, and the structure is scannable.

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

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

For a tool with one optional parameter, strong annotations, and no output schema, the description gives sufficient context about return content (top tools, packs, call volume), data aggregation, and caching. It does not specify the exact return format, but the described structure covers the essentials for agent decision-making.

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

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

The schema fully documents the only parameter `window` with enum values and an explanation of the trade-off. The tool description merely mentions '24h, 7d, or 30d' without adding new semantic information, so a baseline of 3 is appropriate given 100% schema coverage.

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

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

The description states precisely what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window.' It opens with a declarative, informative phrasing ('What other AI agents are calling on Pipeworx right now') that distinguishes it from siblings like discover_tools or recent_alerts by focusing on agent usage trends.

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 three explicit use cases: discovering hot data sources, confirming a canonical tool choice, and aligning with agent needs. It does not mention when NOT to use it or name alternative tools, which would merit a 5, but the use-case list provides clear contextual 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 declare readOnlyHint and idempotentHint true, which the description does not contradict. The description adds substantial behavioral context: the >3pp threshold for partition deviations, the Jaccard similarity anchor, placeholder filtering rules, and the fill check logic that warns against trading when realizable_edge_pp ≤ 0. This is valuable beyond annotation metadata.

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 meticulously structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and fluent prose. Every sentence contributes operational detail, making the length justified for a multi-mode tool. It is front-loaded with the core verb and resource.

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

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

With no output schema, the description fully specifies the response format: opportunities[] with gap_pp, suggested_trade, reasoning, monotonicity violation context, and partition_check fields in event mode. It also explains edge cases like thin_legs and placeholder filtering, ensuring the agent has all needed 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 description coverage is 100%, and the main description greatly enriches the event and topic parameters with concrete examples (e.g., 'fed-decision-may-2026'), mode-specific behaviors, and explanation of internal processes. It goes well beyond the schema's own descriptions.

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

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

The opening sentence clearly states the tool 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', giving a specific verb, resource, and detection method. It distinguishes itself from siblings like polymarket_edges by focusing on arbitrage and describing the algorithmic means.

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 instructs when to use each mode: no args for trending_scan, 'event' for a specific market, and 'topic' for cross-event scanning. It also recommends 'event' vs 'topic' based on user intent and even names an alternative tool (polymarket_fill_risk) for custom sizing, leaving no ambiguity.

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

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

The description goes far beyond the readOnly/idempotent annotations by disclosing internal details: the five model families, slippage assumptions, 24h-move warnings, Fed bets being excluded, and 1-hour caching. It also warns that recent moves may already be priced in, giving agents realistic expectations about edge reliability.

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 (over 300 words) but well-structured with clear sections (model families, response segments, knobs, diagnostics). It is front-loaded with purpose and every sentence carries detailed information. It loses a point for being verbose, but the density and organization justify most of the length.

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

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

Given complexity and no output schema, the description thoroughly explains the response top-level structure (by_segment, fed_candidates, _diagnostics), the filtering behavior, and caching. It also documents edge cases like placeholder slugs and why Fed bets are excluded, making it complete for an agent to invoke and interpret results 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?

Input schema covers all 9 parameters with descriptions (100% coverage), so the baseline is 3. The description adds high-level context by grouping them as 'TRADEABLE-EDGE KNOBS' and explaining how min_liquidity/max_spread_pp drop unrealizable edges and how min_partition_leg_kelly applies to per-leg Kelly. This adds semantic value beyond the schema.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, using a specific verb ('Scan') and resource ('Polymarket markets'). It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on 'what should I bet on today' discovery rather than tracking or arbitrage.

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

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

The description gives clear context (agents discover opportunities without paging hundreds of markets) and explains the tradeable-edge knobs for filtering. However, it does not explicitly name alternatives or state when not to use this tool versus siblings like polymarket_arbitrage, though the differing purposes imply boundaries.

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

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

The description goes well beyond the annotations (read-only, idempotent, open-world) by disclosing important behavioral nuances: snapshot TTL limits, gaps in data due to cache-miss behavior, decay calculation methodology (daily closes, net of slippage), and the meaning of the expired[] array. This is rich, non-obvious context that significantly aids correct interpretation of 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 lengthy but well-structured with ARGS and RESPONSE sections, making it scannable. Each sentence adds valuable detail, and the labeled structure aids comprehension. It earns a 4 rather than 5 because the prose is dense and could be tightened 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 analytical complexity and lack of an output schema, the description fully explains the return format (tracked[], expired[], snapshot_dates[]) and all relevant limitations (TTL, data gaps, decay computation). It provides everything an agent needs to correctly interpret results and set expectations, making it contextually complete.

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

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

The input schema already fully describes both parameters (days, window) with defaults, clamps, and allowed values. The description adds minimal extra meaning, mostly restating the schema information. Since schema coverage is 100%, a baseline of 3 is appropriate; the description provides no substantial semantic addition.

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: tracking edge persistence and decay from daily snapshots, answering a specific analytical question. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical trends rather than current values, and the phrase 'a fresh wide edge and a 3-week-old wide edge are different trades' clarifies the unique value proposition.

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 strong usage context by framing the tool as the answer to 'how long has this edge existed and is it shrinking?' and explaining the trade implications. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of the highest bar for usage guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial transparency beyond these hints, describing exactly what the tool does: walks the order-book ladder, computes top-of-book and VWAP fill prices, identifies thin legs, and flags 'forced_directional_risk.' It also warns about the behavioral consequence of partial fills converting an arb into an unhedged position. This is consistent with the annotations and provides valuable 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 dense but every sentence serves a purpose. It is structured logically: purpose, single-market behavior, basket behavior, and explicit usage guidance with risk warning. Despite its length, it avoids redundancy and front-loads the core purpose, making it easy for an agent to scan.

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 and four nuanced parameters, the description is extremely complete. It enumerates return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, capture_ratio, thin_legs[], max_clean_notional_usd) and explains the financial risk scenarios. This covers all necessary context an agent would need to invoke the tool correctly and interpret its results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description significantly enhances parameter understanding. It explains the mutual exclusivity of market vs event, the meaning of side in each mode, the default values, and the distinct interpretation of size_usd for single-market (spend/proceeds) vs basket (settlement notional per leg). This adds clarity far beyond the schema's field names.

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

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

The description opens with a specific, action-oriented summary: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' This clearly identifies the tool's function and differentiates it from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk and order-book depth. It also explicitly names the two modes (single-market and basket) and the key outputs.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when not to rely on theoretical overround and the risk of partial basket fills, giving clear context for choosing this tool over alternatives.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior, but the description adds substantial behavioral detail: compatibility_warning conditions, temporal_alignment, skipped_cross_type counters, and the distinction between meaningful and meaningless spreads. This far exceeds annotation coverage.

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 densely packs necessary information; it leads with purpose, then modes, response fields, and safety flags. Though somewhat run-on with dash-heavy sentences, each segment adds unique value and the structure is logically ordered.

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

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

Despite no output schema, the description thoroughly covers the response shape (leg-by-leg prices, matched spreads, top_spreads_pp), safety fields, temporal alignment, and skip counters. It explains both failure modes and when spreads are meaningful, making it highly complete for a complex tool.

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

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

The input schema covers 100% of parameters, but the description adds important semantics: topic is a pre-mapped shortcut list, explicit ticker/slug override the mapped sides, and the relationship between parameters is clarified. This supplements the schema descriptions effectively.

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

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

The description clearly defines the tool as computing the cross-venue spread between Kalshi and Polymarket for the same resolving question, with specific modes and response contents. It distinguishes from single-venue siblings by emphasizing the cross-venue focus and the requirement of equivalent bet shapes.

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 both invocation modes (topic shortcuts vs explicit ticker/slug), and strongly warns that pre-mapped topics often return compatibility warnings and are not tradeable. It lacks explicit naming of alternative sibling tools, but the context signals and description orientation give clear usage boundaries.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable context beyond this: scoping to the agent identifier (anonymous IP, BYO key hash, account ID) and the omit-key-to-list-all behavior. It does not contradict annotations, but it doesn't disclose edge-case behavior like missing-key responses.

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 three sentences, front-loaded with the core action, then usage context, then scope and companion tools. Every sentence earns its place with no filler.

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

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

This is a simple tool with one optional parameter and strong annotations. The description covers the main use case, the listing behavior, scope, and relationship to remember/forget. No output schema exists, but the return value is effectively explained ('value previously saved' or 'all saved keys'), making the context complete.

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

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

Schema coverage is 100% (the only parameter `key` is described as 'omit to list all keys'). The description reinforces this by mentioning the omit behavior, but adds little beyond what the schema already provides. 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 opens with a specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes itself from sibling tools by naming remember and forget as its pairing operations, leaving no ambiguity about its role.

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 tells when to use the tool: 'Use to look up context the agent stored earlier' with concrete examples, and highlights the alternative of 're-deriving it from scratch' (when not to use). It also positions itself relative to remember and forget, covering the sibling relationships.

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?

An annotation declares readOnlyHint=true, but the description states 'Set mark_read:true to flag returned events read,' which is a state-modifying operation. This directly contradicts the annotation. The description is transparent, but the annotation conflict forces a score of 1 per rubric.

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

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

The description is slightly long but well-structured: it leads with the main action, then return payload, filtering options, mark_read behavior, and polling/alternative endpoint. Each sentence carries useful information, though the alternative endpoint could be considered extraneous for an agent.

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

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

The description covers return content, filtering, mark_read semantics, polling suitability, and an alternative REST endpoint. It does not explain unread_only behavior or pagination beyond limit, but given the schema details and annotations, it is reasonably complete. The annotation contradiction detracts slightly.

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 all parameters with descriptions (100% coverage), but the tool description adds value by giving an example type ('sec_8k'), explaining the mark_read effect on subsequent calls, and clarifying that filtering can combine type and since. This goes beyond the schema's basic field descriptions.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed alerts) and notes the return payload includes source, citation_uri, and raw event payload. This distinguishes it from siblings like recent_changes by focusing on the subscription feed.

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 context: it is suitable for polling ('Polls work fine') and mentions an alternative REST endpoint for scripts/dashboards. It does not explicitly name a sibling tool to avoid, but the guidance is sufficient for typical use cases.

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

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

Beyond annotations (readOnly, idempotent), the description discloses fan-out to multiple APIs, fallback logic, API sunset causing soft-fail, and return shape (changes[], total_changes, pipeworx:// citation URIs). No contradiction with annotations.

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

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

The description is dense and front-loaded with user-intent examples, but it is lengthy with parenthetical technical details (API specifics, sunset date). Every sentence adds value, though a more compact version could convey the same 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?

With no output schema, the description supplies the return structure and groups by source, covering fallbacks and API failure modes. For a tool with 3 required params and multiple integrated APIs, this is complete enough for an agent to select and invoke it correctly.

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

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

Schema already has 100% coverage with descriptions for type, since, and value. The description reinforces syntax (ISO date vs relative shorthand, CIK zero-padding) and adds how 'since' maps to each data source, which is helpful but not a large leap beyond the schema.

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

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

Description opens with natural-language query examples then explicitly defines the tool as a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It names concrete sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishes itself from sibling entity_profile by stating when to use that instead.

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

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

Provides explicit exclusions: 'Use entity_profile instead when you want the static profile... regardless of window.' It also explains fallback behavior (GDELT preferred, GNews on rate-limit/5xx) and notes USPTO soft-fails, giving agents clear when-to-use versus when-not-to-use context.

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

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

Annotations cover idempotency and non-destructiveness, but the description adds crucial context: persistent vs. 24-hour memory for anonymous sessions, key-value scoping by identifier, and cross-session retention. 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 primary purpose, then provides usage examples, storage details, and pairing guidance. Each sentence adds distinct value with no wasted words.

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

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

For a simple key-value store with two parameters and no output schema, the description covers purpose, when to use, persistence behavior, and related tools. It is complete within 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% and both parameters are well-described. The description mentions 'key-value pair' which reinforces the schema but adds no new parameter-specific semantics beyond what's already structured.

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: 'Save data the agent will need to reuse later' — a specific verb and resource. It distinguishes from siblings by explicitly referencing recall and forget, making its role in the memory workflow 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?

It provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples. It also names alternatives ('Pair with recall to retrieve later, forget to delete'), giving clear context for selection.

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

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

Despite annotations already indicating read-only, idempotent, open-world, and non-destructive behavior, the description adds substantial behavioral context: identifiers are labeled with source, unresolved identifiers are explicitly stated under `unresolved` rather than omitted, and LEI/FIGI enrichment degrades gracefully (EDGAR identifiers still return if GLEIF/OpenFIGI is unavailable). 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 dense but well-structured, starting with user query examples and moving through supported types, behavior, and fallbacks. It is longer than ideal, but each sentence contributes meaningful information about output labeling, unresolved handling, and graceful degradation. Slightly verbose but justified given the tool's complexity.

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

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

For a tool with two entity types and no output schema, the description adequately covers inputs, outputs, failure behavior (explicit unresolved identifiers), and fallback behavior (graceful degradation). It also notes that it replaces 2-3 manual lookups, giving a complete picture of what the tool does and why it's useful.

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 parameter descriptions are clear, but the description adds significant semantic value by specifying accepted input formats per type (ticker, CIK, or name for company; brand or generic for drug). It also provides examples like 'ozempic' and 'metformin,' which clarify the intended usage beyond the schema alone.

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

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

The description clearly states the tool's function: resolving user-spoken names to canonical/official identifiers. It provides concrete example queries ('What's the ticker for…', 'find the CIK for…') and explicitly distinguishes itself from tools that require IDs as input. This is a specific verb+resource pair that differentiates it from siblings like entity_profile.

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

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

The description explicitly instructs 'Use FIRST whenever you have a name but need an ID,' giving clear guidance on when to invoke this tool. It also provides supported entity types and input formats, making the decision straightforward. This is strong usage guidance, even if it doesn't list exclusions.

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

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

Annotations already declare read-only, non-destructive, open-world, and idempotent behavior. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns a structured list with score, confidence, and signal density. This goes beyond the annotations without contradicting them.

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

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

Three sentences, front-loaded with the primary purpose, followed by mechanism and use case. Every sentence carries distinct information: what it does, how it works, and what it returns. 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 explicitly states the return format ('ranked list with score, confidence, signal density per entity'). It covers the key aspect of the tool's behavior, the entity ordering semantics, and a concrete use case. The schema handles the rest of the parameter details, making this complete for a moderate-complexity tool.

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

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

The input schema already covers 100% of parameters, so the baseline is 3. The description further enriches semantics by explaining that the first entry in 'entities' is treated as the 'subject' for narrative and the rest are competitors, and that 'context' disambiguates common names. This adds 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 begins with a specific action and resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes from siblings by explaining it probes each entity with ai_visibility_check and ranks results, which is the batch/comparative variant of the single-entity 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 gives a clear use case ('competitive AI-marketing audits') and an example question, making context clear. It implies this tool is for multi-entity comparison rather than single-entity checking, but does not explicitly state when to prefer the sibling ai_visibility_check for one entity, so no exclusion guidance is present.

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

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

Annotations already declare read-only/idempotent/non-destructive, but the description adds substantial behavior beyond that: composite fan-out, partial failure handling, bundlephobia first-measurement delay of 5-30s, and the sources_failed field. 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 longer than average but every sentence provides distinct value: what, when, return shape, ecosystem scope, and performance caveat. It is well-organized, front-loaded with the core purpose, and no filler.

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

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

There is no output schema, so the description lists all major return components (summary block fields, per-advisory details, links, alternative versions). It also covers ecosystem limitations, partial failure behavior, and timing, making the tool fully usable 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 coverage is 100% (both parameters have descriptions), so the baseline is 3. The description adds no extra semantic detail beyond the schema; it merely references package/version implicitly. The schema already handles scoped packages and version defaulting, so the description does not need to compensate.

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

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

The description clearly states a specific, composite action: a "should I add this npm package" check that fans out to deps.dev and bundlephobia. It distinguishes itself from siblings by naming the data sources and scope (NPM only). The resource (npm package) and verb (scan) are explicit.

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 usage trigger: "Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'." Also provides clear rejection/alternative guidance: "PyPI / Maven / Cargo / Go fall under deps.dev:version directly," which tells agents 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?

Beyond the read-only/idempotent annotations, the description reveals technical behavior: BGE-base-en embeddings, cosine similarity over 500-char windows, and a 200K-character cap with truncation and flagging. It also explains that returned passages include character offsets to enable verbatim verification, adding meaningful operational 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 three sentences and every clause serves a purpose: core functionality, use case, and technical details. It is front-loaded with the key verb/resource and avoids fluff, making it highly scannable.

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

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

For a tool with no output schema, the description sufficiently discloses return shape (passages with offsets and similarity scores), operational limits (200K cap, truncation), and workflow pairing. Combined with rich annotations and full schema coverage, the agent has enough context to invoke it correctly.

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

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

Schema descriptions cover all three parameters at 100%, and the description largely restates their meaning ('text you already pulled', 'top-N passages'). It adds concrete examples (SEC 10-K body, article) and usage context, but these are minor enrichments over the schema's already-detailed parameter descriptions, so it stays at the baseline.

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

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

The description explicitly states the tool performs semantic search inside a fetched record, specifying the action ('search'), resource ('fetched record'), and output (top-N passages with offsets and similarity scores). It also differentiates from siblings like ask_pipeworx_grounded by positioning this as the passage-retrieval step rather than a grounded-answer 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 gives an explicit usage condition: use when the record is too large to fit in the prompt, and it pairs with ask_pipeworx_grounded for a fetch-then-ground workflow. This tells the agent when to choose this tool over alternatives and how it complements them, though it doesn't enumerate excluded scenarios.

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

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

Despite annotations covering idempotency and non-destructiveness, the description adds significant behavioral detail: OAuth account requirement, phone verification, SMS rate cap, webhook signing secret returned once, auto-disabling after 10 failures. This goes well beyond the structured 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 organized with an opening statement, then supported types, then delivery channels. Every sentence adds necessary detail (examples, constraints, URLs). It is dense but not bloated, making efficient use of the space.

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, nested delivery object, no output schema), the description is complete: it covers requirements, examples, return value, delivery behaviors, and limitations. It provides all context needed to use the tool correctly.

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

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

Schema description coverage is 100%, and the schema itself provides detailed examples for each subscription type and delivery channel. The description largely restates these examples and requirements, adding little new parameter-level meaning. Baseline 3 is appropriate since the schema is already comprehensive.

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: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes the subscribe action from sibling tools like list_subscriptions and unsubscribe, and notes the return value (new subscription id).

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 prerequisites (requires Pipeworx OAuth account), supported subscription types with examples, and delivery options. It also implies when to use by mentioning that the feed is always on and can be pulled via recent_alerts, subtly differentiating from read tools. No explicit exclusions, but context is clear.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the output is category-bucketed example questions with exact tool + argument shape, drawn from the live catalog, and the optional `topic` parameter allows focusing. No contradiction with annotations.

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

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

The description is a single, well-structured paragraph that front-loads key example queries, then explains purpose, output, and usage. It is somewhat long due to enumerating multiple example phrasings and categories, but each sentence earns its place by helping an agent recognize intent and configure the call. Could be trimmed, but not to the point of losing 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?

There is no output schema, so the description carries the burden of explaining return values, and it does: 'Returns category-bucketed example questions ... each with the exact tool + argument shape'. It also covers the parameter behavior, examples of topics, and the recommended usage order among sibling tools. For a one-parameter tool with strong annotations, this is fully complete.

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

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

Schema coverage is 100% and the schema already fully describes `topic` with allowed values and the 'omit for cross-category spread' behavior. The description adds only a few examples ('finance', 'pharma', 'betting') that duplicate the schema, plus the verb 'focus' which adds little new meaning. Thus a baseline 3 is appropriate.

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

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

The description clearly states a specific verb and resource: it is the onboarding entry point for an agent wanting to know what to ask Pipeworx, returning categorized example questions with exact tool and argument shapes. It distinguishes itself from sibling tools by positioning itself as the FIRST step before using meta-tools.

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

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

It explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools' and lists example user intents like 'what can you do?' and 'give me ideas'. It also implies when not to use by directing users to the meta-tools once they know their goal.

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 non-destructive and idempotent hints, so the description adds valuable context beyond them: ownership enforcement, row deactivation rather than deletion, and retention of historical events. This enriches the agent's understanding of side effects.

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

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

Two sentences, front-loaded with the primary action, and every phrase adds value. No fluff 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?

For a single-parameter tool with robust annotations and no output schema, the description fully covers what the agent needs to know: what it does, constraints, side effects, and relationship to other tools.

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

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

Schema description coverage is 100% and the parameter description ('Subscription id (uuid) returned by subscribe') is clear. The tool description does not add further parameter semantics, so baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Cancel a subscription by id.' This clearly states the tool's action and object, distinguishing 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?

It provides clear context on when to use the tool: 'you can only cancel your own subscriptions' and notes the effect on historical events via recent_alerts. It lacks explicit exclusions, but the ownership constraint and deactivation semantics are 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?

The description adds substantial behavioral context beyond the annotations: the crucial distinction between could_not_verify (the check did not happen) and unsupported (no source exists), the presence of verification_error{stage,detail}, and the warning not to treat could_not_verify as evidence. It also discloses the fast-path vs grounded pipeline behavior. No contradiction with annotations.

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

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

The description is long but well-structured and front-loaded with trigger phrases. Each section serves a purpose: usage triggers, pipeline routing, return format, and important caller caveats. The could_not_verify warning is essential safety information. It could be slightly tighter, but the complexity of the tool justifies the length.

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

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

Despite having no output schema, the description fully covers return values (verdicts, actual value, citation, reasoning), error semantics, and routing behavior. It also explains how this tool replaces a multi-step call chain. For a tool of this complexity, the description is complete and 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?

The schema already documents both parameters with clear descriptions (100% coverage). The description adds extra meaning for tolerance_pct by explaining the default (implied by wording, capped at 5) and giving a concrete use case ('set 1–2 for hallucination detection'). This goes beyond the schema, justifying a score above the baseline.

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

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

The description starts with natural-language trigger phrases and clearly states the tool's function: natural-language claim verification against authoritative sources. It specifies the distinct sub-paths (SEC EDGAR for company-financial claims, grounded pipeline for all others) and the verdict output, which clearly distinguishes it from sibling research/search tools.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear context. It also explains the routing behavior and how different claim types are handled. However, it does not 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.