Unpaywall

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

Annotations already mark the tool as readOnly, idempotent, and non-destructive. Description adds important behavioral details: default free model, BYO key for Anthropic (cost incurred directly), and return structure (per-model fields). No contradictions.

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

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

Three sentences, each adding essential information. First sentence states purpose and output, second explains models and key usage, third lists use cases. No redundant text.

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

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

No output schema exists, but description partially specifies return fields (score, confidence, signals, raw_response + combined view). Covers the main aspects of a moderately complex tool; slight gap on exact JSON structure but sufficient for selection.

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

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

Schema coverage is 100% (all parameters have descriptions). Description adds value by explaining the default model, that _apiKey is passed directly to Anthropic, and that context helps disambiguate. This goes beyond the schema descriptions.

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

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

Description clearly states the verb 'Probe', the resource 'LLMs for what they know about a business/brand/product/topic', and the output 'score visibility (0-100) per model'. It distinguishes from sibling tools like ask_pipeworx or deep_research by focusing on AI visibility scoring.

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

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

Explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Does not explicitly state when not to use, but the context is clear and the tool is safe (read-only), so the guidance is adequate.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint. Description adds that it routes to 5,245 tools, returns structured answers with stable citation URIs, and works on all tiers. 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?

Long but efficient, front-loaded with key directive. Every sentence serves a purpose: use case, examples, distinctions, scope. Well-structured for an AI agent.

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

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

Despite no output schema, description explains return format (structured answer with citation URIs). Covers main use cases, examples, and behavior 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 coverage is 100% with all parameters documented. Description adds value with usage examples and natural language instruction, but no additional parameter-level semantics beyond schema.

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

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

The description clearly states the tool answers factual questions about current/historical data from over 5,000 verified sources, with citations. It distinguishes from siblings like ask_pipeworx_grounded and deep_research by specifying when to use each.

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

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

Explicitly instructs to prefer over web search, provides specific query types and examples, and tells when to step up to alternative tools. Comprehensive guidance on when to use and when not to.

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. The description adds that no candidate is active currently, so it matches ask_pipeworx exactly, and that it is a full working router with experimental edge. This provides useful context beyond annotations.

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

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

The description is a single paragraph, front-loaded with key points, and every sentence adds value. It is concise and well-structured.

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

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

Given the tool's complexity as a universal router with many tools, the description explains its relationship to ask_pipeworx, current status, and purpose. Without an output schema, it mentions same response shape, which provides enough context for the agent.

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

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

Schema coverage is 100% with each parameter described. The description only states 'same arguments' and does not add new meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states it is a beta version of ask_pipeworx that is identical in tools, arguments, and response shape, used for testing candidate routing improvements. It distinguishes from ask_pipeworx by specifying the experimental nature.

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

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

The description instructs to use it exactly like ask_pipeworx when wanting the newest routing, and mentions that results are compared to stable. It does not explicitly state when not to use, but the comparison with ask_pipeworx implies the alternative.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds extra LLM call cost, return format including refusal reasons, and behavior on success/failure. 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?

Well-structured, front-loaded with key differentiator. Every sentence adds value. Slightly long but justified given complexity. No waste.

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

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

No output schema, so description compensates by fully specifying return format (fields, refusal reasons). Also mentions usage context and cost trade-off. Complete for a tool with this complexity.

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

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

Schema coverage is 100% with all parameters described as aliases for question. Description mentions aliases again but adds no new semantics beyond schema. Baseline 3 is appropriate.

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

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

Clearly states it is a hallucination-resistant answer mode for high-stakes reads, distinguishing from ask_pipeworx by explaining the extraction process using only tool result. Verb+resource (ask grounded) is precise.

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: high-stakes reads where answer will be quoted/cited/acted on and agent must not invent facts. Also states to prefer ask_pipeworx for casual lookups, providing clear exclusion.

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 extensive behavioral context beyond annotations: it explains low-confidence resolution short-circuit, closed market handling, wide spread illiquidity, cancellation rule parsing, news fallback mechanisms, and the parent event extractor. Annotations indicate readOnlyHint=true and idempotentHint=true, which are consistent, but the description enriches the agent's understanding of edge cases and safety behaviors.

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

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

The description is very long and detailed, containing multiple paragraphs, examples, and technical edge cases. While well-structured with section headers, it could be more concise. Every sentence earns its place, but the sheer length may reduce scanability for an AI agent. A tighter focus on essential behavioral rules would improve clarity without sacrificing completeness.

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, absence of an output schema, and 3 parameters, the description is remarkably complete. It covers all major aspects: input format, process, fan-out examples, response shapes, resolver contract, parent event extraction, news fallbacks, safety mechanisms, and cancellation rules. An agent can confidently invoke this tool with minimal ambiguity.

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

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

Schema coverage is 100% (all 3 parameters described), so baseline is 3. The description adds value by clarifying the 'market' parameter's accepted formats and giving examples. For 'depth' and 'include_raw', it provides behavioral context (e.g., 'quick = 2-3 evidence sources', 'false keeps responses under ~20KB'), which helps 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 identifies the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text), describes the process (resolves, classifies, fans out), and states the output (evidence packet + comparison). This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage, which focus on different aspects.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides concrete examples of fan-out for different bet types. However, it does not mention when not to use it or compare to specific sibling tools like polymarket_edges, leaving some ambiguity about 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 (readOnly, openWorld, idempotent), description adds: parallel API call, data sources (SEC EDGAR for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradiction with annotations.

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

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

Description is well-structured, starting with trigger phrases and then detailing behavior. It is slightly verbose but every sentence adds value, making it efficient overall.

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

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

Covers typical use cases, data sources, behavior, and efficiency gains. Lacks mention of limitations (e.g., historical range, rate limits) but is sufficient for a read-only, open-world 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% and parameters already described. Description adds examples ('AAPL','MSFT','ozempic') but does not add new semantic meaning 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 identifies the tool's purpose: side-by-side comparison of 2-5 companies or drugs in a single parallel call. It distinguishes from sequential lookups and provides specific trigger phrases.

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 preference over sequential single-pack lookups and provides context for when to use (comparing entities). Does not mention when-not-to-use, but positive guidance is strong.

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. The description adds extensive behavioral details: decomposes into facets, parallel routing to 5,245 tools, returns findings packet with evidence, confidence, source, fetched_at, pipeworx:// citations, gaps array, hop field, contradictions, and second-hop iteration behavior. No contradiction with annotations.

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

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

The description is somewhat verbose (multiple paragraphs) but well-structured, front-loading critical info (account requirement, alternative). Every sentence adds value, covering purpose, usage, behavior, parameters, and output. Slightly verbose but not wasteful.

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

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

Despite no output schema, the description fully explains the return format (findings packet with evidence, confidence, source, fetched_at, citations, gaps, contradictions). It also covers timing, depth behaviors, and citation structure, making it complete for a complex tool with multiple depth levels and parallel processing.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds extra value by elaborating on depth meanings (quick=3 facets, standard=5 with gap recovery, thorough=8 with iterative chases) and clarifying that the question can be broad/multi-part, which goes beyond the schema's natural language description.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1369 STRUCTURED data sources ... in ONE call'. It explicitly distinguishes from siblings by noting it is not open-web search and contrasting with ask_pipeworx for single lookups.

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

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

The description provides explicit when-to-use ('Best for broad/multi-part questions over structured data'), when-not-to-use ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'), and alternatives ('use ask_pipeworx instead' if not signed in). Also covers account requirements.

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?

Descriptions adds that results include 'names, descriptions, and full input schemas...ready to call directly, no second schema lookup needed', which complements the readOnlyHint and idempotentHint annotations without contradiction.

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

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

Front-loaded with main purpose and usage guidance. The list of domains is lengthy but necessary to convey the tool's broad applicability. Minor redundancy ('top-N...', 'each result is ready to call') could be streamlined.

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

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

Covers purpose, when to use, behavioral traits, and parameter semantics adequately. Lacks details on return format but compensates by stating results include schemas and are callable directly, which is sufficient given 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%, so baseline is 3. The description explicitly lists aliases for query (task, q, description, search) and mentions limit, adding value beyond the schema's parameter 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 explicitly states 'Find tools by describing the data or task' and provides extensive domain examples (SEC filings, FDA drugs, etc.), making the purpose concrete and distinct from sibling tools.

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

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

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set', giving clear when-to-use guidance. Does not explicitly state when not to use, but the 'FIRST' implication provides sufficient context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds behavioral details: fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific fields with examples, mentions a sunset for patents API with soft-fail, and fallback mechanisms. This is comprehensive beyond annotations.

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

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

The description is lengthy but every sentence adds value. It is front-loaded with purpose and usage examples. While it could be more structured with bullet points, the density of information is appropriate for a complex multi-source 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 complexity (no output schema, two parameters, multiple data sources), the description covers what the tool returns (cik, recent filings, fundamentals, patents, news, LEI) and caveats (patents API sunset, soft-fail). It lacks mention of rate limits or data freshness, but the openWorldHint mitigates that. Overall, it provides sufficient context for correct invocation.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaning beyond schema by explaining the accepted formats (ticker or zero-padded CIK) and emphasizing that names are not supported. It also clarifies that 'type' only supports 'company' currently.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call.' It gives concrete examples of usage ('Tell me about X', 'research Acme', 'brief me on Tesla') and distinguishes itself from siblings by explicitly stating to prefer this over chaining single-pack lookups.

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

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

The description explicitly advises when to use this tool ('ALWAYS PREFER over chaining... when the user asks for a holistic view') and when not to ('names not supported — use resolve_entity first if you only have a name'). It provides clear context and alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context on usage scenarios (e.g., stale context, clear sensitive data) but does not clarify idempotency behavior. 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?

Three sentences: core action, usage guidance, and related tools. Every sentence adds value 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?

The tool has a single parameter and no return schema. The description covers purpose, when to use, and related tools, fully sufficient for its simplicity.

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

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

Schema coverage is 100%, so the schema already describes the 'key' parameter. The description provides no additional meaning beyond 'by key,' meeting 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 clearly states the action 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes from sibling tools like 'remember' and 'recall' by implication of 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?

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also provides guidance on pairing with 'remember' and 'recall' as alternatives.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behaviors. The description adds procedural context: fetches the page, extracts title/description/key links, and outputs standard markdown format. This goes beyond annotations without contradicting them, earning a 4.

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

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

The description is concise with three sentences: purpose/benefit, process, use cases. It's front-loaded and each sentence adds value without redundancy.

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

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

Given the parameter count (2), full schema coverage, and lack of output schema, the description sufficiently explains the output format (single text blob, markdown, ready to drop) and use. Annotations cover safety and idempotency. The AI agent has all needed context to invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The tool description does not add new semantic information about parameters beyond what the schema provides (e.g., url format, max_links default/max). It reiterates the extraction process but doesn't clarify parameter behavior further.

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: generating a production-ready llms.txt file for any URL. It specifies the resource (llms.txt for a URL) and the action (generate). It also distinguishes it from sibling tools by mentioning specific use cases like indexing for AI crawlers, which no sibling tool addresses.

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

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

The description lists explicit use cases: getting a client's site indexed, drafting for own project, auditing competitor's AI presence. While it doesn't mention when not to use or compare to siblings, the sibling list shows no overlap, making the context clear. A score of 4 reflects this clarity without exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds the output structure, which aids understanding of tool behavior. No contradictions; behavioral disclosure is sufficient given 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 a single, well-structured sentence that front-loads the core action and then lists return fields. No superfluous text; every word 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?

With an output schema present (implied by context signal), the description does not need to explain return values in depth, but it does so briefly. Full input specification and clear output description make it complete for a simple 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 includes a description and examples for the DOI parameter. The tool description adds minimal extra meaning beyond the schema, so baseline 3 applies.

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

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

The description clearly states the tool's function: fetch open-access status and the best free legal copy given a DOI. It specifies the inputs (DOI) and outputs (is_oa, oa_status, best location, journal metadata), distinguishing it from sibling tools like search_papers.

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

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

The description explicitly mentions the input (DOI) and what it does, so usage context is clear. However, it does not provide explicit guidance on when not to use it or compare to alternatives, which prevents a perfect score.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering safety. The description adds value by listing returned fields (id, type, etc.) and confirming read-only 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?

Two informative sentences with zero fluff, front-loaded action and returned fields, then usage guidance. Every sentence earns its place.

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

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

Despite no output schema, the description enumerates return fields. For a simple list tool with one parameter and strong annotations, the description is complete and leaves no ambiguity.

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

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

Schema coverage is 100% with a clear description for include_inactive. The tool description reinforces that the parameter controls inclusion of cancelled subscriptions, but doesn't significantly enhance 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 it lists the caller's active subscriptions, specifying the verb (list), resource (subscriptions), and scope (caller's active). This distinguishes it from sibling tools like subscribe and unsubscribe.

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

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

Explicitly advises when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and alternatives.

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

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

Discloses rate limit (5 per identifier per day), free usage, and that it doesn't count against quota. Annotations are all false and 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?

Single paragraph, front-loaded with purpose, then guidelines, constraints, and impact. Every sentence adds value, no wasted words.

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

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

Complete for a feedback submission tool with 3 parameters, enum, and nested object. No output schema needed; description covers usage, constraints, and behavioral context.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces schema details and adds important context like not pasting prompts, which 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?

Explicitly states the tool's purpose: sending feedback (bug, feature, data_gap, praise) to the Pipeworx team. Clearly distinguishes from sibling tools, which are primarily query/investigation 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?

Provides detailed when-to-use for each feedback type, and explicitly says not to paste end-user prompts. Includes context about team reading and roadmap impact.

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=false. Description adds value beyond annotations: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This provides data source, privacy, and caching 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 two concise sentences plus a bulleted list of use cases. Every sentence is informative, front-loaded with purpose, and no wasted words.

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

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

The tool has 1 optional parameter, no output schema, and annotations cover safety. Description covers behavior, data source, privacy, caching, and use cases, making it fully informative for an agent to invoke correctly.

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

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

Schema coverage is 100% for the single parameter 'window' with enum and description. Description adds: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds comparative guidance beyond the schema.

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

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

The description clearly states that the tool returns top tools, top packs, and total call volume over a recent window (24h, 7d, 30d). It distinguishes itself from siblings by focusing on trending data from other AI agents, and provides three specific use cases.

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

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

The description provides explicit when-to-use guidance with three bullet points (discovering hot data sources, confirming canonical choice, seeing use case alignment). It does not mention when not to use or alternatives among siblings, but gives context for window length 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?

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description details behavioral traits: monotonicity checks, partition sum checks, semantic similarity threshold (≥0.30 Jaccard), partition filter (placeholders), and fill check against live CLOB depth. No contradiction with annotations.

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

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

The description is detailed and structurally sound: starts with overview, then explains modes, then fills in specifics like semantic anchor, partition filter, fill check. Every sentence provides value, though it is relatively long; could be slightly more concise but still effective.

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

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

Completeness is high: explains response format (opportunities[], partition_check, fill_check), contextualizes with sibling tools (polymarket_fill_risk), and covers all key behaviors. No output schema but description adequately explains return values.

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

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

Schema descriptions are 100% covered, but the description adds substantial meaning: explains that event expects a Polymarket event slug (or full URL), topic expects a seed question, and details the different behavior modes and constraints (e.g., semantic anchor, partition filter).

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific use cases, and references sibling tools for related 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 explains when to call with no args (trending scan), when to use event (specific market), and when to use topic (cross-event scanning). Provides guidance on when not to trade (realizable_edge_pp ≤ 0) and mentions custom sizing via polymarket_fill_risk.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds significant transparency by detailing caching behavior ('Cached 1h at the KV level'), the internal model families and their parameters, and the structure of the response including diagnostics for empty segments. This exceeds the minimum expected from annotations.

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

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

The description is front-loaded with the core purpose but becomes dense and lengthy with technical details about model families and edge cases. While comprehensive, it could be more streamlined by separating high-level usage from algorithmic specifics. The structure is logical but verbose.

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

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

Given the complexity (9 parameters, multiple segments, no output schema), the description thoroughly explains the response structure, edge cases (empty segments, Fed bets), and the meaning of key result fields (edge_pp_net, kelly_fraction, etc.). It covers why segments might be empty and includes caching details, making it complete for an agent to use correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description mentions the knobs at a high level (e.g., min_liquidity, max_spread_pp) but does not add substantial per-parameter meaning beyond the schema descriptions. It provides context for how knobs work together but not extra detail on individual parameters.

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

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

The description clearly states the verb ('Scan top Polymarket markets and return opportunities') and the resource ('where Pipeworx data disagrees with market price'). It specifies the intended use case ('what should I bet on today') and distinguishes the tool from siblings like polymarket_arbitrage by emphasizing the data disagreement approach.

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

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

The description implies usage for daily bet discovery but does not explicitly state when not to use this tool or compare it to alternatives such as polymarket_arbitrage or polymarket_edge_tracker. The context is clear but lacks exclusions or direct comparisons.

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 as true and destructiveHint as false. The description adds valuable behavioral context: history bounded by 60-day TTL, decay computed from daily closes (not intraday), and details on computed fields like trend and decay_pp_per_day. No contradiction with annotations.

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

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

The description is well-structured: opening purpose, then detailed response fields, then limitations. While somewhat long, every sentence adds value and the bullet-like format for RESPONSE improves readability. It could be slightly more concise, but overall effective.

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

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

No output schema exists, so the description must fully explain return values. It does so comprehensively: tracked array with full time-series, first_seen, trend, decay; expired array with lifespan_days; snapshot_dates. It also explains data source (cache-miss driven), limits (TTL, snapshot start), and scaling of decay. Complete for a time-series analytical 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% for the two parameters. The description adds context beyond schema: explains 'days' default/clamping (though schema says clamp 2-30, description says max 30) and describes 'window' as snapshot family. This extra clarification merits a 4.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering a specific question about edge longevity. It distinguishes itself from sibling tool polymarket_edges (which likely provides current snapshots) by focusing on historical tracking and trend computation.

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

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

The description provides explicit context for when this tool is relevant (e.g., distinguishing fresh vs old edges) and explains the meaning of response fields (tracked, expired, snapshot_dates). It does not explicitly state when not to use it or mention alternatives, but the guidance on interpretation is sufficient for typical use.

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

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

Despite annotations declaring readOnlyHint=true, the description adds rich behavioral context: walks the ladder, returns a verdict (clean|degraded|cannot_fill), warns about forced_directional_risk and the danger of partial fills. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections for modes and a list of return fields. Every sentence adds value, though some minor redundancy could be trimmed. Still, it is efficient for the complexity.

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

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

Without an output schema, the description comprehensively lists all return fields and explains their meaning. It covers edge cases (thin_legs, forced_directional_risk) and provides the verdict logic. This gives the agent sufficient information to decide and interpret results.

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

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

Schema coverage is 100% with parameter descriptions. The tool description adds extra semantics: clarifies interpretation of size_usd for single-market vs basket, default side logic for basket, and clamps. This goes beyond the schema, raising the 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?

Explicitly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. Clearly distinguishes two modes (single-market and basket) and provides the return fields. Directly references sibling tools (polymarket_arbitrage, polymarket_edges) to indicate when to use this tool.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Gives strong rationale: theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an unhedged directional position (dominant loss mode).

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 safety. Description adds rich behavioral context: two modes, response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters), and explains why spreads might be meaningless (temporal misalignment, non-equivalent bet shapes). Exceeds annotation coverage.

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

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

The description is front-loaded with the core purpose and well-organized into modes and safety fields. The safety section is somewhat lengthy but packed with essential context. Every sentence adds value, though slight 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?

No output schema exists, so the description must explain the response. It does: raw probabilities, matched spreads, compatibility_warning, temporal_alignment, skipped counters. All return fields are described. Parameter count and optionality are clear. The description is complete for an informed 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 descriptions for all three parameters. The description adds meaning by explaining the topic parameter lists the 10 shortcuts and that explicit tickers override topic mappings. Examples in the schema reinforce usage.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies the verb (cross-venue spread) and resources (Kalshi, Polymarket), and distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison and introducing two modes.

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

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

The description explains when to use: to compare prices across two venues when bet shapes are equivalent. It provides two modes (topic shortcuts or explicit tickers) and warns that pre-mapped topics often return compatibility warnings. It does not explicitly state when not to use but implies it via the warnings. The sibling list includes other polymarket tools, but no direct comparison is made.

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, destructiveHint, idempotentHint. Description adds scope (identifier-based) and pairing context, no contradictions.

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

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

Three sentences, front-loaded with action, every sentence adds value. No waste.

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

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

Simple tool with one optional param, description covers purpose, usage, scope, and pairing. No output schema but return value is implicit.

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 100%, but description adds meaning by explaining dual behavior of key parameter (retrieve vs list).

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

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

Description clearly states it retrieves a value saved via remember or lists all keys, with concrete examples like ticker, address, notes. Distinguishes from siblings remember and forget.

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

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

Explicitly describes when to use (look up context) and when to omit key (list all). Mentions pairing with remember/forget, though does not explicitly state when not to use.

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

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

The description states that setting mark_read:true flags returned events as read, implying a write side effect. However, annotations include readOnlyHint=true, which indicates no write operations. This contradiction severely undermines transparency.

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

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

The description is four sentences, each adding essential information—purpose, return fields, parameter usage, and alternative access. No redundant or filler content; efficiently front-loaded with the main action.

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

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

Given no output schema, the description adequately explains return fields (source, citation_uri, raw payload) and parameter usage. It covers common use cases like filtering and pagination limits, but lacks mention of error conditions or authentication requirements, leaving minor gaps.

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

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

With 100% schema description coverage, the baseline is 3. The description adds significant value by explaining each parameter in context (e.g., 'Filter by type (e.g. "sec_8k")', 'ISO timestamp', 'set mark_read:true to flag returned events read') and providing usage rationale, exceeding the schema alone.

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

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

The description states a specific verb ('Pull') and resource ('fired events from your subscription feed'), clearly identifying the tool's function. It distinguishes itself by specifying return fields and filtering options, though no direct sibling differentiation is provided; however, the purpose is unambiguous.

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

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

The description mentions that polling works fine and provides an alternative access method (GET registry.pipeworx.io/alerts.json), but does not explicitly state when to use this tool versus sibling tools or exclude unsuitable contexts. The guidance is present but not comprehensive.

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

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

Annotations indicate read-only, idempotent, open-world. Description adds details on data sources (SEC, GDELT/GNews, USPTO), failure modes (GDELT rate-limited, PatentsView sunset), and return structure. No contradiction with annotations.

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

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

Description is front-loaded with examples and use cases. It is detailed but every sentence serves a purpose. Slightly longer than necessary for a concise description, but still effective.

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

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

Given the rich annotations, complete schema coverage, and detailed description covering sources, failure modes, and return structure, the description is fully complete 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?

Schema coverage is 100%. Description adds meaning by explaining accepted formats for 'since' (ISO date or relative shorthand like '7d', '30d'), 'value' (ticker or zero-padded CIK), and enum for 'type'. Provides example usage 'AAPL' and '0000320193'.

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: 'change feed for a company in the last N days/weeks/months' with concrete examples like 'What's new with X' and 'latest on Y'. It explicitly distinguishes from the sibling tool entity_profile.

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

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

Provides explicit guidance: 'Use entity_profile instead when you want the static profile...' and explains the tool fans out to multiple sources. The context signals and sibling list confirm this is well-differentiated.

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 idempotentHint=true and destructiveHint=false. The description adds scoping by identifier and persistence duration (permanent vs 24h), which are valuable beyond annotations. Could mention overwriting behavior, but overall good.

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 purpose, every sentence adds value. No wasted words. Excellent for quick comprehension.

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 (two params, no output schema), the description covers purpose, usage, behavior, and companion tools thoroughly. No gaps for an agent to use correctly.

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

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

Schema covers both parameters with examples. Description adds context about key-value nature and scoping, enhancing understanding beyond the schema. No missing 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 saves data for later reuse, with specific examples like ticker, address, preference. It distinguishes from siblings by naming recall and forget, making the purpose explicit and actionable.

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

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

Explicitly states when to use (discover something worth carrying forward) and pairs with recall and forget. Provides clear context for the agent to decide when to invoke this tool.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds that it 'cascades through several lookup endpoints internally' and replaces multiple manual lookups, providing useful behavioral context beyond annotations.

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

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

The description is slightly verbose but well-structured, starting with examples and then providing purpose and details. It is front-loaded and informative, though it could be slightly 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?

The description explains the return data (ticker, CIK, company name, citation URI for companies; RxCUI, ingredient, brand for drugs) and notes internal cascading. Given no output schema, this is adequate coverage 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%, so baseline is 3. The description repeats the schema's parameter descriptions exactly, adding no new semantic information. Therefore, it does not improve upon 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 resolves a name to a canonical identifier, with examples of queries. It distinguishes itself from sibling tools by saying 'Use FIRST whenever you have a name but need an ID'.

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

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

Explicit guidance is given to use it first when a name needs an ID, and it provides specific query examples. It does not explicitly name alternatives, but the context implies it is the initial step before other entity-based 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 indicate read-only, idempotent, non-destructive. Description adds: 'Probes each entity with ai_visibility_check, ranks by score, surfaces most/least, returns ranked list with score, confidence, signal density.' This fully discloses the process and output 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 is action-oriented and front-loaded, second adds context and output format. Every word adds value without redundancy.

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

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

Given 4 well-documented parameters, no nested objects, and annotations covering safety, the description explains the composite behavior and output format sufficiently despite lacking an output schema.

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

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

Schema coverage is 100% with descriptions. Description adds crucial nuance: 'First entry treated as the subject for narrative; rest are competitors.' Also explains model options: 'workers-ai (free default), anthropic (requires _apiKey)'. This supplements 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 starts with 'Compare AI visibility across multiple entities side-by-side', clearly stating the action and resource. It differentiates from sibling 'ai_visibility_check' (single entity) and 'compare_entities' (generic) by specifying the process of probing with ai_visibility_check and ranking.

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

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

Explicitly states use case: 'Useful for competitive AI-marketing audits'. Provides an example question. However, it does not explicitly mention when not to use or alternatives beyond the implicit difference from siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed list. No contradiction with annotations.

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

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

The description is a single dense paragraph, informative but somewhat packed. It effectively uses front-loading but could benefit from bullet points for readability. Still concise and to the point.

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 covers return values (summary block fields, per-advisory detail, links, alternative versions). It also explains partial failure behavior, timing caveats, and ecosystem limitations, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, so parameters are well-documented in schema. The description adds minor nuance (scoped packages accepted, default version behavior) but does not significantly extend schema 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 it is a composite check for npm packages, combining deps.dev and bundlephobia data to answer whether to add a package. It uses specific verbs like 'scan' and 'checks', and distinguishes from siblings by focusing on npm dependency evaluation.

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

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

The description explicitly tells when to use: when an agent asks about safety, popularity, or size of an npm package. It also clearly scopes to NPM ecosystem and directs other ecosystems to deps.dev:version, providing clear alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description focuses on disclosing key behaviors: pagination ('Returns up to 50 results per page') and optional filtering ('restrict to OA-only'). These add value beyond annotations without contradiction. A score of 4 reflects good supplementary behavioral info.

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 extremely concise: two sentences, front-loaded with the key action, then optionality and result limit. Every sentence contributes essential information without redundancy or fluff.

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

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

Given the tool's simplicity (3 parameters, straightforward search) and the existence of an output schema (so return values need not be explained), the description covers the main points: search scope, optionality, and page size. It misses ordering or default sort, but for a search tool this is acceptable. Hence 4.

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

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

The description adds little beyond the input schema, which already fully documents all three parameters (100% coverage). While it echoes the OA restriction, it does not enrich understanding of parameter format or constraints. According to the rule, baseline 3 is appropriate when schema coverage is high.

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 ('keyword search'), resource ('scholarly papers via Unpaywall'), and scope (optional OA restriction, pagination). It effectively distinguishes from siblings by specifying 'scholarly papers' and 'Unpaywall's coverage', making its domain unique among similar tools like search_within or deep_research.

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

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

The description implies usage for keyword search on scholarly papers but does not explicitly tell when to use this tool versus alternatives like deep_research or search_within. It provides context (e.g., OA filter, 50 results per page) but lacks exclusions or direct comparisons, so it scores at the 'implied usage' level.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds highly valuable behavioral details: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag, and offset-bearing passages. No contradictions.

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

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

The description is concise and well-structured. It starts with the core purpose, then details usage context, pairing suggestions, technical specifics, and constraints. Every sentence adds value without redundancy.

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

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

Despite lacking an output schema, the description clearly outlines return values (top-N passages with offsets and scores). All relevant aspects—input size limits, embedding model, windowing, pairing with sibling, and output details—are covered, making it complete for an agent to use correctly.

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

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

Schema coverage is 100%, but the description enriches parameter understanding: explains 'text' as the document to search, provides natural-language examples for 'query', and clarifies 'limit' as max passages (1-20, default 5). This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool performs semantic search inside a fetched record, returning passages with character offsets and similarity scores. It distinguishes itself from sibling tools by mentioning pairing with ask_pipeworx_grounded, making the purpose unambiguous.

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

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

Explicitly tells when to use: when the record is too big to fit in the prompt. Also provides an alternative workflow (pair with ask_pipeworx_grounded) and explains benefits like saving context and offset-based verification.

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?

Description adds significant behavioral context beyond annotations: creation of subscription, return of ID, delivery channel details, phone verification requirement, and rate limits. 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?

Description is detailed but not overly verbose. Key information is front-loaded; however, some sections (e.g., delivery details) could be slightly trimmed without losing clarity.

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

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

For a complex tool with 3 parameters (including nested objects) and no output schema, the description covers all essential aspects: subscription types, parameter formats, delivery channels, authentication, and limitations. No missing information.

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 enriches each parameter with concrete examples and use-case-specific details (e.g., item codes for sec_8k, topic for polymarket_edge). Delivers meaning beyond the schema.

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

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

Description clearly states it creates a proactive monitoring subscription to a live-data event stream, distinguishing it from siblings like 'unsubscribe' and 'list_subscriptions'.

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

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

Provides explicit context for when to use (setting up monitoring), required account type, and lists supported types. Lacks explicit 'when not to use' but is otherwise very 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, idempotentHint, etc. The description adds behavioral details: it returns dynamic example questions drawn from a live catalog, explains the no-argument full spread vs topic-focused call, and notes it's an onboarding entry point—no side effects are implied.

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

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

The description is somewhat lengthy but well-structured: common questions front-loaded, followed by explanation of output and usage. Every sentence adds value, though slightly verbose for a simple 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?

Despite no output schema, the description fully explains what is returned (category-bucketed example questions with tool+argument shape) and how to invoke. It also places the tool in the broader context of onboarding, making it complete for its purpose.

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 one optional 'topic' parameter described with examples. The description adds value by stating omission gives a cross-category spread and listing example values. Sufficient but straightforward.

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 as an onboarding entry point, listing common user intents (e.g., 'What can I ask Pipeworx?') and specifying it returns category-bucketed example questions with tool+argument shapes. It distinguishes from siblings by advising to use this first when the agent doesn't know Pipeworx's capabilities.

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 use 'when you do not yet know what Pipeworx can do for you' and suggests passing an optional topic to focus. It also references meta-tools to learn how to call them, providing clear when-to-use context.

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

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

Annotations declare idempotentHint true and destructiveHint false; the description adds valuable context that the row is deactivated not deleted, and that historical events remain available via recent_alerts. This goes beyond what annotations provide.

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

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

The description is extremely concise: two sentences, no wasted words. The first sentence immediately states the action and key constraint, and the second provides important behavioral nuance. Perfectly 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?

For a simple cancellation tool with one parameter and no output schema, the description covers the essential behavioral outcomes (ownership check, deactivation, historical data availability) and even cross-references another tool (recent_alerts). Minor gaps: no mention of error cases or return value, but these are not critical given the tool's simplicity.

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

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

Schema coverage is 100% with a clear description for the 'id' parameter. The tool description adds the context of ownership enforcement but does not elaborate further on the parameter's format or constraints beyond what the schema already states. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Cancel') and resource ('subscription by id'), clearly distinguishing the tool's action. It also adds nuance about ownership enforcement and the deactivation effect, setting it apart from related tools like list_subscriptions or 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?

The description explicitly states ownership enforcement ('you can only cancel your own subscriptions'), providing clear when-to-use context. However, it does not explicitly mention when not to use it or suggest alternatives like a hard-delete tool.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, indicating safety. The description adds detail about the internal pipeline routing (structured SEC EDGAR for financial claims, grounded pipeline for others), the verdict categories returned, and the inclusion of verbatim evidence and reasoning – all beyond what annotations provide.

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

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

The description is a few sentences long, each earning its place: trigger phrases, usage instruction, pipeline explanation, return value description, and efficiency claim. It is well-structured and front-loaded with key purpose information, though 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?

Given no output schema, the description fully explains return values (verdict, actual value with citation, reasoning). It covers the two claim processing pipelines and defines the verdict options. With only 2 parameters and 100% schema coverage, the description provides complete context for an agent to understand tool behavior and expectations.

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 meaning for tolerance_pct by explaining its override behavior and suggesting values for hallucination detection, which goes beyond the schema description. The claim parameter is adequately described but not 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 starts with natural-language trigger phrases ('Is it true that...', 'fact check') that clearly map to the tool's purpose. It explicitly states natural-language claim verification against authoritative sources and distinguishes itself by noting it replaces 4-6 sequential calls, setting it apart from sibling tools like ask_pipeworx or deep_research.

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

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

The description says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear usage context. It further separates claim types (company-financial vs. other) but does not explicitly state when not to use it or list specific alternative tools, though the sibling list implies other options for non-factual queries.

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