Data Providence

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

Annotations declare readOnlyHint, idempotentHint, etc. The description adds value by noting default model (Workers AI Llama) is free, _apiKey passed to Anthropic (BYO key), and return structure (per-model + combined). No contradictions.

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

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

Two sentences front-loaded with core purpose and output. Second sentence covers details efficiently. Every sentence adds value; no fluff.

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

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

Despite no output schema, the description summarizes return structure (per-model + combined). Covers all parameters, required fields, use cases, and cost implications. 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%, so baseline is 3. Description adds context: default model behavior, _apiKey usage, and purpose of 'context' parameter for disambiguation. Exceeds baseline with useful extra meaning.

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

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

The description uses specific verbs ('Probe', 'score') and clearly defines the resource ('LLMs') and output ('visibility (0-100) per model'). It distinguishes from siblings like 'ask_pipeworx' (specific dataset) and 'scan_competitor_ai_presence' (focused on competitors).

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 cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Also explains when to provide _apiKey (for Anthropic probing). Lacks explicit 'when not to use' but provides clear context.

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

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

The description adds useful behavioral context beyond the annotations: it discloses that the tool dynamically routes to the right sub-tool, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. Annotations already cover read-only, open-world, and idempotent behavior, and the description does not contradict 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 front-loaded with the most important selection signal ('PREFER OVER WEB SEARCH') and uses compact, illustrative examples. It is somewhat long due to the domain list and repeated web-search emphasis, but each section supports tool selection without significant waste.

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

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

For a parameter-light router with rich annotations and no output schema, the description covers input format, output behavior (structured answer with citation URIs), scope, and usage triggers. An agent has enough information to invoke it correctly without missing critical details.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for the single 'question' parameter. The description contributes example questions and trigger phrases but adds no new parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: it routes natural-language factual questions to one of 5,743 tools across 1,500 sources and returns structured answers with citations. It distinguishes the tool from web search, but it does not explicitly differentiate it from sibling tools such as ask_pipeworx_beta, ask_pipeworx_grounded, deep_research, or query.

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

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

The description gives strong when-to-use guidance: prefer over web search for current or historical data, with specific trigger phrases and examples. However, it lacks explicit when-not-to-use guidance or references to alternative sibling tools, so it stops short of a 5.

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

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

Beyond the readOnly, idempotent, and destructive annotations, the description discloses that this variant runs live candidate routing improvements when one is under test and currently has none active. This is valuable non-obvious behavior: the tool may change behavior over time relative to the stable router, and the description also clarifies it does not fall back to anything.

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

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

The description is dense but every sentence earns its place: identity/equivalence, current experimental state, usage instruction, and a final clarification against fallback assumptions. It is front-loaded with the most important information and contains 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?

For a read-only, idempotent routing tool with full schema coverage, the description covers the needed context: beta status, current equivalence to stable, when to prefer it, and confirmation that it is a complete router. Referencing the same response shape as ask_pipeworx is sufficient given that sibling is present in the same tool suite.

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 the question parameter and all aliases (q, text, input, query, prompt) already documented in the input schema. The description adds no parameter-level semantics beyond noting that the arguments are the same as ask_pipeworx, which does not exceed the baseline for a fully documented 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 identifies the tool as 'Beta version of ask_pipeworx' and an 'identical universal router (same 5,743 tools, same arguments, same response shape)', making its action and scope unambiguous. It also distinguishes it from the stable sibling by naming ask_pipeworx and framing this as the experimental edge with candidate routing improvements.

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

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

It explicitly says to use it exactly like ask_pipeworx when you want the newest routing, giving a clear when-to-use condition. It also states the current no-candidate state means it matches ask_pipeworx exactly, and clarifies it is a full working router rather than a fallback stub.

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

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

The description discloses the exact success and refusal return shapes, lists all refusal_reason enum values, explains that answers come only from tool results, and notes the extra LLM call cost. This goes well beyond the annotations' read-only and idempotent hints.

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

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

The description is dense but every sentence earns its place: purpose, behavior, return format, refusal reasons, usage criteria, and cost tradeoff. It is front-loaded with the most important differentiator and structured logically.

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?

All essential invocation context is provided: what the tool does, when to use it, what it returns, how it refuses, and how it differs from its sibling. The lack of an output schema is mitigated by the explicit return contract in the description.

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

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

The schema already fully documents the single required parameter and all aliases at 100% coverage. The description adds no new parameter-level meaning, so the schema carries the burden; this matches the baseline for high 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 clearly states this is a hallucination-resistant answer mode for high-stakes reads, using a specific verb and resource. It explicitly contrasts itself with ask_pipeworx, making the distinction between grounded extraction and ordinary lookup obvious.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete examples. It also names the alternative, ask_pipeworx, and says to prefer it for casual lookups.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. Description adds extensive behavioral details: fan-out logic, resolver contract, parent_event extractor, news fallback, safety checks for low-confidence, closed markets, wide spreads, and cancellation rules. Far exceeds annotation burden.

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

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

Description is very long and dense with detailed sections. While well-organized with all-caps section markers and clear labeling, it could be pruned for an agent. However, every sentence appears to earn its place given the complexity of 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?

Given the tool's complexity (multiple categories, response shapes, edge cases), the description is extremely complete. Covers resolver confidence, parent events, news fallback, safety mechanisms, cancellation rules, and more. No output schema, so description carries full burden.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. Description adds substantial context: explains market parameter accepts slug/URL/text, depth has quick/thorough with defaults, and include_raw explains when to use true vs false. Clearly adds value beyond schema.

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

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

Description clearly states it researches Polymarket bets by pulling Pipeworx data in one call. Accepts slug, URL, or question text. Returns evidence packet and market-vs-model comparison.Distinguishes itself among many siblings by being the dedicated bet research tool.

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

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

Explicitly lists use cases like 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides extensive examples of fan-out per category and when certain fields are relevant. No explicit when-not, but the guidance is thorough.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds critical details: company data includes latest 10-K revenue/net income/cash/debt with off-calendar handling, drug data includes FAERS counts, FDA approvals, trial counts. Results sorted by primary metric. No contradiction.

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

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

While packed with useful information, the description is slightly verbose. However, it is well-structured with examples and clear instructions, earning its length. Minor nit for conciseness.

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

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

No output schema exists, but description explains returns (paired data + citation URIs). Covers key use cases and data sources. Could mention pagination or edge cases, but overall adequate for the tool's complexity.

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

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

Schema coverage is 100% with both parameters described. Description adds context: enum values 'company'/'drug', array constraints (2-5 items), and examples (tickers for company, drug names). Exceeds 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 clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, with specific data sources (SEC EDGAR for companies, FAERS/FDA for drugs). It distinguishes from sibling tools like entity_profile by emphasizing parallel lookup over sequential.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and provides example queries ('compare X and Y', 'which is bigger'). Gives clear context for when to use this tool versus alternatives.

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

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

Annotations already declare read-only, non-destructive, idempotent. Description adds value by listing returned fields and usage hint for resource_id, going beyond annotation basics.

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 efficient sentences, front-loaded with action and results. Every word adds value, no repetition or 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?

Combined with annotations and full schema, description fully covers purpose, inputs, output hints, and next step. No gaps for a search tool.

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

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

Schema covers all parameters with 100% description coverage, so description need not add much. Baseline 3 is appropriate; description doesn't enhance parameter meaning.

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

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

The description clearly states the tool searches a specific open data catalog by keyword, with precise verb+resource+scope. It distinguishes from 25+ sibling tools as a focused dataset search.

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

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

Describes return fields and next step (pass resource_id to query/metadata). Missing explicit when-not-to-use or alternative tools, 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 already declare readOnlyHint=true, but the description goes much further: it reveals account/plan gating, parallel decomposition and routing, the findings packet shape, explicit gaps[] and contradictions[], citation fetchability semantics, semantic excerpting, and expected latency ranges. This is rich behavioral context beyond the annotations and beyond the schema.

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

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

The description is long, but almost every clause carries distinct operational information: prerequisites, alternatives, decomposition behavior, output fields, caveats, and latency. It is front-loaded with the most critical gating info (account/plan requirement) and then moves to usage guidance. Slight structural denseness and long parentheticals keep it from a perfect score.

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

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

Despite having no output schema, the description fully compensates by explaining the return packet, gaps[], contradictions[], hop field, citations, and latency behavior. It also covers prerequisites, depth options, and alternatives. An agent has what it needs to decide whether to call this tool and to interpret the result at a high level.

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

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

Schema coverage is 100%, and the schema already documents the depth enum and the question parameter in detail. The description adds value by clarifying that depth:'thorough' requires a paid plan and by describing how 'standard' and 'thorough' behave with gap recovery and contradiction scanning, which is genuinely supplementary.

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

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

The description states a specific, distinctive purpose: grounded multi-source research across Pipeworx's 1500 structured data sources in a single call, explicitly distinguishing itself from open-web search and from sibling tools like ask_pipeworx. It also gives concrete example use cases and contrasts with single-lookup tools, making it easy for an agent to select.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: use ask_pipeworx if not signed in, use ask_pipeworx for single lookups, and use deep_research for broad/multi-part questions over structured data. It also names the prerequisite account/plan requirement, leaving little to inference.

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

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

Annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) indicate safe, read-only behavior. The description reinforces this by stating it 'returns' tools and 'no second schema lookup needed,' implying no mutations. It adds value beyond annotations by detailing the return format (names, descriptions, full schemas with examples) and indicating results are directly callable.

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

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

The description is well-structured: opens with purpose, lists use cases, describes return, and ends with usage guidance. It is slightly verbose (e.g., listing many domains), but each sentence contributes value. No redundancy with schema, and front-loaded with the core action.

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

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

Given no output schema, the description fully explains what is returned: top-N tools with names, descriptions, full input schemas, and curated examples. It also clarifies that results are ready to call without additional lookups. This is sufficient for an agent to understand the tool's capability and output format.

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

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

Schema coverage is 100% with clear property descriptions for 'query', 'q', 'task', etc. The description does not add significant new parameter meanings, though it provides natural language examples and confirms alias usage. Since the schema already covers semantics fully, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and distinguishes it from siblings by emphasizing it returns top-N tools with full schemas, ready to call. This differentiates it from other search/tool-lookup tools like datasets or query.

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

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

Explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Also lists when to use ('when you need to browse, search, look up, or discover what tools exist for...') and provides examples. No exclusionary statements, but the 'FIRST' directive implies priority over other tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, and the description adds substantial behavior beyond them: USPTO API sunset soft-fail, expected-empty FDA sections for small-molecule companies, GDELT→GNews fallback, sources_used/sources_failed semantics ('an empty section is a real no data, not a bug'), resolved_from/resolved_to behavior, and the private-company notes line. This actively prevents an agent from misinterpreting empty or partial 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 front-loaded with trigger phrases and the ALWAYS-PREFER rule, which is the right structure. However, it is a single dense wall of text covering ten-plus return sections with no bullet points, line breaks, or section headers, making it harder for an agent to parse quickly. Every sentence carries information, so it is dense rather than verbose, but the lack of scannable structure costs it a higher score.

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

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

There is no output schema, so the description bears the full burden of explaining return values — and it does, enumerating every data section (cik, recent_filings with URIs, fundamentals with sort order, patents, federal_contracts, fda_products, hiring, news, LEI) plus failure modes and caveats. For a tool this complex (cross-source fan-out across 9+ sources), nothing an agent needs to correctly invoke it and interpret its response 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 description coverage is 100%, so the baseline is 3, but the description adds concrete example values ('AAPL', '0000320193', 'Moderna'), reinforces that type='company' and type='ticker' are interchangeable, and clarifies the name-resolution path and zero-padded CIK expectation. These are usability enhancements over the schema rather than fully new semantics, which only slightly raises the score above 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?

States a specific verb and resource: 'full cross-source profile of a US public company in ONE parallel call.' Multiple trigger phrases ('Tell me about X', 'brief me on Tesla', 'company profile for Microsoft') leave no ambiguity about what request this serves. The holistic cross-source scope distinguishes it from siblings like resolve_entity (single resolution), compare_entities (multi-entity comparison), and single-pack SEC/news 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?

Provides explicit trigger phrases and a clear preference rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also covers the edge case of private companies, which return resolved:false rather than failing. However, it never explicitly says when NOT to use this tool in favor of adjacent siblings like compare_entities or resolve_entity, so exclusion guidance is incomplete.

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 destructive and idempotent hints. The description adds context on what is deleted but does not disclose additional behavior like error handling or side effects. Moderate added value over 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 waste. Action verb first, usage guidance, and sibling references all efficiently included.

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

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

Simple tool with one parameter, annotations covering destructive/idempotent, and no output schema. The description fully informs the agent when and how to use the tool.

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

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

Schema coverage is 100% and already describes 'key' as 'Memory key to delete'. The description repeats 'by key' without further detail, adding minimal 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 specifies the verb 'Delete', the resource 'previously stored memory', and the method 'by key'. It clearly distinguishes from sibling tools 'remember' and 'recall'.

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

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

Explicit usage scenarios given: stale context, task done, or clearing sensitive data. Pairing with remember/recall is mentioned. No explicit when-not-to-use, but the positive cases are clear.

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

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

The description adds significant context beyond annotations: it explains the process (fetches page, extracts title/description/links) and output format. No contradictions with annotations.

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

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

The description is a single paragraph of about four sentences, front-loaded with the main action. Every sentence is informative and earns its place.

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

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

Given low parameter count, full schema coverage, and rich annotations, the description is complete. It explains the output format (text blob) sufficiently for a tool with no output schema.

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

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

Schema coverage is 100%. The description adds detail beyond schema: default max_links (25) and maximum (50), and clarifies that url is the site to summarize. This adds 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 clearly states the tool generates a production-ready llms.txt file for any URL, specifying the output format and use cases. It uses a specific verb and resource, and distinguishes 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?

The description explicitly lists three use cases: indexing a client's site, drafting for own project, auditing competitor. While it doesn't state when not to use, the context is clear and provides good guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds return fields and caller scoping, which is useful but not essential beyond annotations.

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

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

Two sentences with no filler: purpose, return values, and usage guidance included concisely.

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

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

Given the simple tool with optional parameter and no output schema, the description covers all necessary behavioral and usage aspects.

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

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

Schema covers the only parameter completely (100%). Description does not add extra meaning beyond implying 'active' default, so baseline score is appropriate.

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

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

Description clearly states it lists the caller's active subscriptions and specifies the returned fields. It distinguishes from sibling tools like subscribe/unsubscribe.

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

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

Explicitly advises using this tool to review subscriptions before adding more or to find an ID to cancel, providing clear context.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, indicating a safe, idempotent read operation. The description adds value beyond these by specifying the exact output details (columns, types, row count, category, last-updated), giving the agent a precise expectation of what data will be returned without needing to invoke the tool. This is useful behavioral context.

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

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

The description is a single, well-structured sentence that front-loads the key action and resource. Every word is informative, including the example and the list of metadata attributes. There is no redundancy or irrelevant information, making it efficient and easy to parse.

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

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

Given the tool's simplicity (one required parameter, no output schema), the description is fully complete. It explains what the tool does, what the input is (with an example), and what the output contains. There are no gaps, as the annotations cover safety and idempotency. The description alone is sufficient for an agent to understand and 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?

The input schema has 100% parameter description coverage, with a clear description for 'resource_id'. The description provides an example ('vank-fyx9'), which adds context but does not introduce meaning beyond the schema. Since the schema already documents the parameter adequately, the description's contribution is marginal, warranting a 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 retrieves schema and metadata for a Providence Open Data dataset, using the specific verb 'Get' and naming the resource. It lists specific attributes (columns, types, row count, etc.) and provides an example resource_id, leaving no ambiguity about its function. It also differentiates from siblings like 'datasets' by focusing on metadata retrieval.

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

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

The description provides clear context and an example, but does not explicitly state when to use this tool versus alternatives. It does not offer exclusion criteria or mention other tools that might be more appropriate for similar tasks, such as 'datasets' tool. This lack of comparative guidance limits its utility for tool 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?

The description discloses behavior beyond annotations: the claim_token flow for later retrieval, the daily rate limit ('5 per identifier per day'), and that it is 'Free; doesn't count against your tool-call quota.' Annotations only state non-read-only and non-destructive, so this context is genuinely additive.

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 each sentence earns its place, covering purpose, usage, exclusions, token mechanics, and rate limits. It is front-loaded with the purpose and could be slightly better structured with clearer paragraph breaks, but it avoids redundancy and wasted words.

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

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

The description covers all relevant context: when to use, when not to use, how to provide feedback, what the claim_token does, rate limits, and cost/free status. No output schema exists, but the description explains the return token sufficiently. It is complete for a feedback-reporting tool with moderate 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%, satisfying the baseline of 3. The description adds further value by advising how to structure the message ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and by clarifying the claim_token usage pattern, moving it above 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 opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly states the tool's purpose and distinguishes it from siblings like ask_pipeworx, which is for asking questions rather than submitting feedback.

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 scenarios ('Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... or when something worked surprisingly well') and an explicit exclusion ('ONLY for tools served by this Pipeworx connection... file it with that server instead'). This leaves no ambiguity about when to invoke it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds self-aggregating signal from CF analytics, no PII, and caching details (5min-1h). No contradictions.

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

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

Concise, front-loaded with key output, then use cases, then technical details. Every sentence is informative with zero redundancy.

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

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

Given simple tool (1 param, no output schema, rich annotations), description fully covers what it returns, how to use, caching, and privacy. No gaps.

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

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

Single parameter 'window' with enum values. Description adds meaning beyond schema by explaining the trade-off between short and long windows. Schema coverage is 100%.

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

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

The description clearly states the tool returns trending tools, packs, and call volume over a recent window. It distinguishes itself from siblings by focusing on real-time usage by other AI agents.

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 three explicit use cases (discovering hot data sources, confirming canonical tool, aligning use case) and guidance on window selection (shorter for hot, longer for steady-state).

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds significant behavioral context: Jaccard similarity threshold (≥0.30), partition placeholder filter (>20% placeholder returns null), live CLOB depth fill check (realizable_edge_pp ≤ 0 means don't trade). No contradiction with annotations.

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

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

Well-structured with clear sections for each mode, but somewhat verbose. Essential information is present and front-loaded, but some redundancy could be trimmed.

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

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

Despite no output schema, the description details response structure (opportunities[], partition_check, fill check fields). However, it doesn't list all possible sub-fields comprehensively, leaving minor gaps for an agent.

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

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

Schema coverage is 100% with meaningful descriptions. Description adds rich context: examples of event slugs ('fed-decision-may-2026'), topic seed questions ('Fed rate decision'), and behavior details for each parameter.

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

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

The description states a specific verb ('find') and resource ('arbitrage opportunities on Polymarket') with clear methods ('monotonicity violations + partition-sum checks'). It distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection.

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 guides when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also provides when-not-to-trade guidance via fill check and refers to polymarket_fill_risk for custom sizing.

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

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

The description extensively covers behavioral traits beyond annotations, including caching (cached 1h at KV level keyed on knobs), model families and their details, tradeable-edge knobs, response diagnostics explaining empty segments, and why Fed bets are excluded. This adds significant value over annotations (readOnlyHint, etc.) with no contradiction.

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

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

The description is front-loaded with purpose but becomes very verbose with technical details on model families, knobs, and diagnostics. While every sentence adds value, its length could overwhelm an agent; more structured formatting would improve conciseness.

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

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

Despite no output schema, the description explains the response top-level structure (by_segment, fed_candidates/fed_note, _diagnostics) and key fields (edge_pp_net, kelly, etc.). It covers filter skips and segment emptiness. However, a high-level summary of the exact output format is slightly lacking.

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

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

Schema description coverage is 100% with thorough parameter descriptions in the schema. The tool description does not significantly enhance parameter meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price, with the explicit purpose of 'what should I bet on today'. This distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker by focusing on model-driven and structural arbitrage opportunities generated by Pipeworx data.

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 context on when to use the tool (discovering betting opportunities without paging hundreds of markets) and explains exclusion of Fed bets from ranking with reasoning. However, it does not explicitly state when not to use it or mention alternatives among siblings beyond the implicit scope.

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 idempotentHint. Description adds critical behavioral details: limitations (60-day TTL), decay computation from daily closes, response structure with tracked/expired/snapshot_dates, and sign conventions. No contradiction.

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

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

Description is detailed and well-structured with clear sections. Every sentence adds value, though it is slightly long. Could be more tightly organized (e.g., bullet points) but maintains readability.

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

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

Despite no output schema, description fully documents the response structure (tracked, expired, snapshot_dates) with field details, limitations, and computation notes. Very comprehensive.

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

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

Schema coverage is 100% with descriptions. Description adds context: default and max for days, default for window, and explains the role of window as 'snapshot family'. This aids understanding beyond the schema.

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

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

Description explicitly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question and is clearly distinct from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

Description provides context on when to use (e.g., differentiating a fresh edge from an old one) but does not explicitly name alternative tools or state when not to use. Still, the usage 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?

While annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds rich behavioral context: it walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns about forced_directional_risk. This goes well beyond the annotations, giving the agent a thorough understanding of the tool's behavior.

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

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

The description is lengthy but well-structured, with clear sections for single-market and basket modes, and uses capitalization for emphasis. Every sentence adds value given the tool's complexity, though it could be slightly more concise without losing detail.

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

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

Despite lacking an output schema, the description comprehensively explains return values for both modes, including fields like verdict, capture_ratio, profit_usd, thin_legs, and forced_directional_risk. It also covers edge cases and provides enough context for the agent 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%, but the description adds significant value: it explains that size_usd in basket mode is 'settlement notional S (shares per leg; each share pays $1),' and that side auto-defaults based on partition sum for baskets. This contextualizes parameters beyond their schema definitions, especially for the basket mode.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It specifies two modes (single-market and basket), making it easy to understand the tool's scope and distinguish it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale (theoretical overround is not capturable, partial basket fills cause unhedged directional positions), providing clear when-to-use and when-not-to-use guidance.

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

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

Even with readOnly/idempotent annotations, the description goes far beyond them: it discloses the matching methodology (keyword overlap, not shared resolution source), fee-modeling limitations, compatibility codes, skipped-leg counters, and temporal alignment semantics. This is unusually transparent about the tool's limitations.

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 labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core definition. There is some redundancy—'EITHER mode' and 'NOT the same as confirmed-aligned' are repeated—but the density is justified given the tool's complexity and absence of an output schema.

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

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

With no output schema, the description carries the full burden of explaining the return shape, and it does: leg-by-leg prices, top_spreads_pp, compatibility codes, temporal_alignment semantics, fees_note, and skipped-leg counters. An agent has enough context to invoke the tool correctly and interpret results without additional documentation.

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 all three parameters fully, so the baseline is 3. The description adds meaningful context: topic shortcuts auto-fetch the matching event, explicit tickers override the mapped side, and both modes run the same matcher. This adds behavioral meaning beyond the schema's type-level descriptions.

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

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

The description opens with a specific definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this from sibling tools by focusing on cross-venue comparison, and its two-mode breakdown makes the tool's 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?

The description gives concrete guidance on both modes—pre-mapped topic shortcuts and explicit ticker/slug pairings—and warns that most pre-mapped topics are not tradeable today. It does not explicitly name an alternative tool when this one is inappropriate, but it sets clear expectations about when results should be trusted and how to read safety fields.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds the nuance of SoQL clauses without leading $ and confirms return format as JSON, providing useful context beyond annotations.

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

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

Two sentences: first introduces purpose with example, second details parameters and output. No extraneous text; efficient and front-loaded.

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

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

Covers the core functionality, parameter usage, and return format. Could mention default limit (schema covers it) but otherwise complete for a query tool without output schema.

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

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

Schema coverage is 100% with good parameter descriptions. The description adds critical detail about omitting the '$' prefix in SoQL clauses, which is not in the schema, and clarifies the purpose of each parameter class.

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 runs a SoQL query against a Socrata dataset, specifies the resource_id format, and lists the filter parameters. It distinguishes itself from the 'datasets' sibling tool which lists available datasets.

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

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

The description implies usage for querying data but does not explicitly state when to use this tool versus alternatives like 'datasets' for listing. No exclusion criteria or context are provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so description adds scoping context ('Scoped to your identifier...') which goes beyond annotations. No contradictions.

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

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

Description is concise with three sentences, no redundant information, and front-loads the core action. Every sentence adds value.

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

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

Given the simple parameter set and rich annotations, the description covers purpose, usage, and scoping well. It omits explicit error behavior (e.g., if key not found), but the use case is straightforward.

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

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

Schema coverage is 100%, and description adds practical nuance: omitting key lists all keys, and keys are saved via remember. This adds value beyond the bare schema.

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

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

The description clearly states the verb 'retrieve' or 'list' and the resource ('value previously saved via remember' or 'all saved keys'). It distinguishes from sibling tools like 'remember' and 'forget' by explicitly mentioning pairing.

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 concrete examples of when to use (e.g., 'the user's target ticker, an address, prior research notes') and context ('look up context the agent stored earlier... without re-deriving it from scratch'). Does not explicitly mention when not to use or alternatives, but the pairing with remember and forget is implied.

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

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

Annotations declare readOnlyHint=true, implying no side effects, but the description states setting mark_read:true flags events as read, a state mutation. This contradicts the annotations. Additionally, the description lacks clarity on other behavioral aspects like rate limits or data freshness.

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 purpose, and each sentence adds necessary context. No redundant or unnecessary 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 5 optional parameters and no output schema, the description covers purpose, filtering, mark_read behavior, polling suitability, and alternative access. It mentions return fields but lacks explicit structure of the response, which is acceptable for a feed tool.

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

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

Schema description coverage is 100%, providing baseline 3. The description adds value by explaining the effect of mark_read and unread_only in the context of tracking read status, and gives an example for type filtering. This slightly exceeds 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 clearly states the tool pulls fired events from a subscription feed, specifying the data elements (source, citation_uri, raw payload). It distinguishes itself from siblings like list_subscriptions by focusing on event retrieval and providing filtering options.

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

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

The description explains filtering by type and since, and the mark_read flag for pagination. It mentions the same feed is available via REST for scripts/dashboards, providing an alternative usage context. However, it does not explicitly state when not to use this tool versus siblings.

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

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

Discloses fan-out to multiple sources, GDELT→GNews fallback, USPTO soft-fail condition, and return structure with citation URIs. No contradiction with annotations (readOnlyHint, idempotentHint).

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

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

Well-organized with examples at the start, then technical details. Slightly verbose but every sentence adds useful information.

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

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

Given the tool's complexity (multi-source, fallback, soft-fail, various inputs, no output schema), the description covers all behavioral aspects comprehensively.

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

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

Schema already covers all parameters with 100% description coverage. Description adds value by explaining type enum limitation, providing concrete examples for since, and clarifying value accepts ticker or CIK.

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

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

The description clearly states it's a change feed for a company covering SEC filings, news, and patents. It includes example query patterns and explicitly distinguishes itself from sibling tool entity_profile.

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

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

Provides explicit guidance on when to use this tool ("What's new" queries) and when to use entity_profile instead (static profile). Also explains date formats and typical monitoring values.

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 write operation (readOnlyHint=false) and idempotent (idempotentHint=true). Description adds retention details: authenticated users get persistent memory, anonymous 24h. No contradictions.

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

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

Four sentences, front-loaded with purpose. Every sentence adds value without redundancy. Clear, succinct, and well-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 2-param tool with no output schema and annotations present, the description fully covers storage scope, duration, and usage pattern. No gaps remain.

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 both key and value with descriptions. The description adds naming conventions for keys (e.g., 'subject_property') and clarifies value can store any text, slightly enriching 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 saves data for reuse across conversations/sessions, with specific examples (ticker, address, preference). It distinguishes from siblings like recall and forget.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and provides after-actions: pair with recall to retrieve, forget to delete. No ambiguity about when to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety is covered. The description goes far beyond annotations by explaining graceful degradation ('LEI/FIGI enrichment degrades gracefully'), internal cascading ('Each call cascades through several lookup endpoints internally'), how ambiguity is handled (returns `figi_candidates` instead of asserting), and explicit unresolved fields. It also discloses that every identifier is source-labelled. This is rich behavioral context that the annotations do not provide.

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

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

The description is long but every sentence carries essential information for correct invocation. It starts with natural-language triggers, then specifies supported types and their resolution logic, covers edge cases, and ends with a note about replacing manual lookups. Front-loaded with the most critical usage guidance ('Use FIRST'). While dense, it avoids fluff; the length is warranted by the complexity of the tool. A thorough agent would benefit from all details.

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

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

With no output schema, the description must convey what the tool returns. It does: mentions `figi_candidates` for ambiguous matches, `unresolved` for failed identifiers, source-labelled identifiers, and specifics for each type (CIK, ticker, LEI, FIGI, RxCUI, ingredient, brand). It also covers input constraints (e.g., 'exactly as printed' for bond issuers). The description is comprehensive enough for an agent to confidently call the tool and interpret results, including error/fallback behavior.

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% (both type and value have descriptions). The description adds extra value beyond the schema: for the `value` parameter, it provides explicit instruction to pass the ENTITY NAME ONLY, with a concrete example of a bond issuer and what to omit. It also clarifies type-specific behavior (e.g., ISIN resolves to legal entity via GLEIF). This enriches the schema's basic descriptions, justifying a score above the baseline 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 explicitly states the tool resolves user-spoken names to canonical/official identifiers needed by other tools, and enumerates supported types ('company', 'drug') with specific identifier outputs. It distinguishes itself from siblings by framing it as the 'first' tool to use when converting a name to an ID, and it clarifies what it does not do (e.g., asserting on ambiguous names). This is a specific verb ('resolve'), a clear resource (identifiers), and enough detail to differentiate from tools like entity_profile or compare_entities.

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

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

The description gives strong guidance on when to use the tool: 'Use FIRST whenever you have a name but need an ID.' It also provides examples of natural-language phrases that trigger it. However, it does not explicitly mention alternative tools or when NOT to use it beyond the ambiguity case. It implies exclusion by saying 'other tools require as input,' but does not name siblings like entity_profile or compare_entities. The 'when' is explicit, but the 'when-not/alternatives' is only implicit.

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. Description adds that it internally calls 'ai_visibility_check' per entity and ranks results, providing behavioral insight beyond annotations.

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

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

Two sentences, front-loaded with purpose, then details. Every sentence is informative with no redundancy.

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

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

Despite no output schema, description fully covers return values (ranked list with score, confidence, signal density). Inputs, process, and outputs are all described adequately.

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

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

Schema has 100% coverage, baseline 3. Description adds meaning: entities are brand/business names, first is subject; context disambiguates common names. This adds value over schema alone.

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

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

Description clearly states verb 'Compare', resource 'AI visibility across multiple entities', and distinguishes from sibling 'ai_visibility_check' which checks single entities. It specifies output: ranked list with score, confidence, signal density.

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 case ('competitive AI-marketing audits') with an example question. Implicitly distinguishes from single-entity check, but does not explicitly list when not to use or provide alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral details: fans out to two services, returns a summary block with specific fields, mentions possible 5-30s delay for bundlephobia first measurement, and describes graceful partial failure behavior.

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

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

Despite its length, every sentence serves a purpose. The description is front-loaded with the main composite check purpose, followed by use cases, return format, and caveats. No redundant 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 comprehensively covers what the tool does, what it returns, limitations (NPM only, bundlephobia first-measurement delay), and partial failure behavior. With no output schema, it adequately describes return values.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context beyond schema: version defaults to latest, and scoped packages are accepted. This provides useful clarification.

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

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

The description clearly states that the tool performs a composite check for evaluating npm packages, fanning out to deps.dev and bundlephobia. It specifies the verb 'scan' and resource 'dependency', and distinguishes from siblings by noting that other ecosystems are handled by deps.dev:version directly.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also advises that for non-NPM ecosystems, users should use deps.dev:version directly, providing clear guidance on when to use versus alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the agent knows it's safe and idempotent. The description adds important behavioral details: truncation at 200K chars with flag, embedding model, chunking over 500-char windows, and output format (passages with offsets and scores). No contradictions.

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

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

The description is relatively concise given the amount of useful information. It front-loads the core purpose and usage, then adds technical details. A slight reduction in length could improve conciseness, but the structure is effective.

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

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

The tool has no output schema, but the description fully explains the return value (top-N passages with character offsets and similarity scores). It covers all necessary context: pairing with sibling tool, embedding model, chunking strategy, character limit, and truncation behavior. Complete for the tool's complexity and lack of output schema.

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

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

Schema coverage is 100%, so the parameter descriptions are already present. The description adds operational context (e.g., max chars for text, natural-language query examples) and explains the output format, which indirectly adds parameter meaning. However, the parameter descriptions themselves are not significantly enhanced 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 performs semantic search inside a fetched record, specifies the use case (when record is too large for prompt), and contrasts with sibling tools like ask_pipeworx_grounded. It includes technical details (BGE-base-en, cosine, 500-char windows, 200K char cap) that precisely define the tool's functionality.

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

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

Explicitly tells when to use ('when the record is too big to cram into the prompt') and provides alternative pairing with ask_pipeworx_grounded. The description gives clear context for when this tool is appropriate versus alternatives.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=true, etc.), the description adds crucial behavioral details: OAuth requirement, anonymous/BYO limitations, type-specific parameters, delivery channels with constraints (phone verification, daily caps, webhook HMAC signing, auto-disable after failures). 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 relatively concise given the detailed information it conveys. It is front-loaded with the main purpose, followed by requirements and type-specific details. Could be slightly more structured (e.g., bullet points) but every sentence adds value.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description is highly complete. It covers return value ('Returns the new subscription id'), all supported types, delivery channels, constraints, and failure behavior. No gaps remain.

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

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

With 100% schema coverage, the baseline is 3, but the description significantly enriches parameter understanding by providing concrete examples for each type (e.g., sec_8k items, polymarket_edge topic, fred_series series_id) and detailed delivery channel specifications (E.164 format, email validation, webhook signing).

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 creates a proactive monitoring subscription to a live-data event stream, a specific verb-resource combination. It clearly distinguishes from sibling tools like 'unsubscribe' and 'recent_alerts' by focusing on creation and listing supported types.

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

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

The description provides clear context for using the tool (to set up proactive monitoring) but does not explicitly discuss when not to use it or mention alternative sibling tools like 'list_subscriptions' or 'unsubscribe' for comparison.

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

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

Annotations already indicate readOnly, openWorld, idempotent, not destructive. The description adds that it returns 'category-bucketed example questions with the exact tool + argument shape drawn from the live catalog', 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?

The description is somewhat long listing many categories, but it is front-loaded with example queries and structured. Every sentence adds value, though it could be slightly more concise.

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

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

For a tool with no output schema, the description explains the return value (category-bucketed example questions with tool shapes) and covers both invocation modes (no args vs topic). It is complete for its purpose as an onboarding tool.

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

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

Schema coverage is 100% with a clear description of the 'topic' parameter. The description gives examples like 'finance, pharma, betting' which matches the schema's enum list, but does not add new meaning beyond what the schema already provides.

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

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

The description clearly states this is the onboarding entry point for a new agent, answering 'what can I ask?'. It distinguishes itself from sibling tools like ask_pipeworx by specifying its role as a discovery tool for example questions and tool 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 explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also provides options: no arguments for full spread, or topic to focus. No explicit when-not-to-use, but the context is clear.

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

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

The description adds significant context beyond annotations: ownership enforcement, soft-delete behavior, and historical event availability via recent_alerts, while annotations provide idempotent and non-destructive hints without contradiction.

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

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

Two sentences, front-loaded with purpose, no unnecessary words. Every sentence adds value.

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

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

For a simple tool with one parameter, no output schema, and good annotations, the description covers ownership, deactivation, and historical data retention completely.

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

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

Schema coverage is 100% and the description does not add new details about the single 'id' parameter beyond what the schema already provides (uuid from subscribe).

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

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

The description clearly states the action 'Cancel a subscription by id', which is specific and distinct from siblings like 'subscribe' or 'list_subscriptions'.

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

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

It explains ownership enforcement (can only cancel own subscriptions) and that the row is deactivated not deleted, but does not explicitly contrast with alternatives beyond stating ownership constraint.

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

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

Annotations already declare readOnly/idempotent/non-destructive behavior, satisfying the safety profile. The description goes further by explaining failure semantics: could_not_verify means the check did not happen and carries verification_error, unsupported means no source covers the claim, and both must be interpreted differently from confirmed/refuted. 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 lengthy but information-dense; every sentence contributes (examples, routing logic, return structure, failure modes, efficiency). It is front-loaded with query patterns and follows a logical outline, though it could be tightened without 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, but the description compensates by enumerating the verdict values, stating the return includes the actual value with pipeworx:// citation and reasoning, and detailing error handling for could_not_verify. This gives enough context for an agent to invoke the tool 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 has 100% description coverage, so the baseline is 3. The description adds meaningful nuance for tolerance_pct, explaining it overrides the claim-wording-implied tolerance and recommending 1–2% for hallucination detection. This goes beyond the schema's simple type/range description.

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

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

The description opens with natural-language query patterns ('Is it true that…' / 'fact check') and clearly states the core function: natural-language claim verification against authoritative sources. It differentiates from siblings by noting it replaces 4–6 sequential calls and by routing company-financial claims vs. other claims to different pipelines.

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 whenever the agent needs to check whether something a user said is factually correct.' It also gives concrete guidance on when the structured SEC EDGAR path is used versus the grounded pipeline, and clarifies the important distinction between could_not_verify and unsupported verdicts, helping callers avoid misusing results.

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