Rhea

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by specifying the default model, cost implications (BYO key for Anthropic), and return structure (score, confidence, signals, raw_response, combined view). It does not contradict annotations.

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

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

The description is concise with four sentences, no fluff, and front-loaded with the main purpose. Each sentence adds value, covering usage, parameters, return format, and use cases.

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

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

Given no output schema, the description adequately details the return format (per-model and combined view). It covers usage context, model options, and key requirements, 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% with clear descriptions for all 4 parameters. The description adds minor context about the default model and API key relationship, but does not significantly expand beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model, with a specific verb and resource. It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on scoring across multiple models and mentioning default model and optional Anthropic integration.

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

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

The description explicitly mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and provides guidance on API key usage for Anthropic. However, it does not explicitly compare to siblings or state when not to use this tool, missing some differentiation.

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

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

Annotations already declare safe, idempotent read behavior. The description adds valuable context: returns structured answers with pipeworx:// citation URIs, routes to one of many tools, and is a single fast call. No contradictions with annotations.

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

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

The description is front-loaded with the key recommendation and packed with useful guidance. Every sentence serves a purpose, though slightly 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 tool's complexity (routing to many sources) and lack of output schema, the description thoroughly explains return format (structured answer with citations), usage context, and relationships to siblings. Complete for an AI agent.

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

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

Schema coverage is 100%, so the description adds minimal meaning beyond stating the question parameter is natural language. It lists aliases, but the schema already documents them.

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 with authoritative structured data. It distinguishes itself from siblings like 'ask_pipeworx_grounded' and 'deep_research', and specifies when to use web search instead.

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

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

Explicit guidance is provided: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with clear alternative tools. Example query types are listed.

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, idempotentHint, etc. The description adds significant behavioral context: it explains the refusal mechanism with specific reasons, the return structure (answer, evidence, confidence, source, fetched_at, refusal_reason), and mentions an extra LLM call cost. 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 moderately long but well-structured, front-loading the purpose. Every sentence contributes useful information (mode, routing, behavior, refusal reasons, cost, use cases). Minor redundancy could be trimmed, but overall efficient.

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

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

Given the complexity (4,927 tools, 1293 sources) and lack of output schema, the description provides a complete picture: success return fields, refusal reasons, and explicit caveats (extra cost, when to use). No gaps for an agent to invoke incorrectly.

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

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

Schema description coverage is 100% with all parameters documented. The description does not add meaning beyond the schema; it mentions 'fills arguments' but doesn't detail parameter semantics. Baseline score 3 is appropriate.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode' for high-stakes reads. It specifies the verb 'ask' and the resource 'Pipeworx' with a grounded mode, and distinguishes itself from the sibling 'ask_pipeworx' by emphasizing fact-only extraction.

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: 'whenever an answer will be quoted, cited, or acted on' in domains like financial verdicts, legal claims, medical lookups, and public statements. It also advises preferring the cheaper 'ask_pipeworx' for casual lookups.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, etc. The description adds extensive behavioral details: resolver contract, parent event extraction, news fallback mechanisms, safety checks for low-confidence matches, closed markets, wide spreads, and resolution-rule risk. This goes well 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 very long and includes many details (fan-out examples, response shapes, resolver contract). While front-loaded with main purpose, it could be more concise. Some details might be better in separate documentation.

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 and absence of an output schema, the description is remarkably complete. It covers input formats, classification categories, fan-out examples, response structure (market, analysis, evidence), safety behaviors, resolution risk, and edge cases. It leaves no major gaps for agent understanding.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant meaning beyond schema: it explains the market input can be slug, URL, or text; depth parameter has fan-out examples; include_raw is explained with rationale. This adds value beyond the schema descriptions.

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

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

The description clearly states the tool researches Polymarket bets by pulling relevant Pipeworx data in a single call. It specifies exactly what it does (research a bet) and the resource (Polymarket data). Although it doesn't explicitly contrast with sibling tools, the unique purpose is evident and the description is highly specific.

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

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

The description provides explicit use cases: 'Use for should I bet on X, what does the data say about Y, or is there edge in Z.' It gives clear context but does not list when not to use it or mention alternatives, though sibling tools exist.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds rich detail: for company type, it pulls specific financial data from SEC EDGAR/XBRL including off-calendar handling; for drug type, it pulls FAERS counts, FDA approvals, trials. Also mentions 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 slightly long but well-structured with front-loaded examples and clear sections. Every sentence adds value, no redundancy. Could be more concise but remains effective.

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

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

Despite no output schema, description explains returns: paired data plus pipeworx:// citation URIs per entity, and that results are sorted by primary metric. Covers both entity types thoroughly, including data sources and sorting behavior. Complete for a tool of this complexity.

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

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

Input schema covers both parameters (type, values) with descriptions, achieving 100% coverage. Description enhances this by specifying enum values (company, drug), giving concrete examples (e.g., tickers for company, drug names), and clarifying constraints (2-5 items, specific formats). Adds value beyond schema.

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

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

Description clearly states the tool does 'side-by-side comparison of 2–5 companies or drugs' and provides example queries like 'compare X and Y' and 'rank these companies'. It distinguishes from sibling tools like entity_profile, which would handle single entities.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and explains what it replaces (8-15 sequential lookups). Provides clear context for when to use, though does not explicitly list alternatives or 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?

Aligns with annotations (readOnly, openWorld, idempotent, not destructive) and adds extensive behavioral details: returns findings with evidence, gaps, contradictions, hop field, and citation URIs. Discloses account requirement and paid plan for thorough depth. No contradictions with annotations.

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

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

The description is well-structured with clear paragraphs covering account requirements, core functionality, usage comparisons, depth details, and output characteristics. It front-loads essential information and 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 thoroughly explains the return structure (findings packet with evidence, confidence, source, fetched_at, citation, gaps, contradictions, hop field). It covers all aspects needed 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?

Both parameters have schema descriptions, and the description adds significant meaning beyond the schema, especially for the depth parameter (explaining the number of facets, gap recovery, contradictions scan) and the question parameter (noting that broad/multi-part questions are fine). Schema coverage is 100%.

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

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

The description clearly states that the tool performs grounded multi-source research across 1293 structured data sources, decomposing questions into facets and routing to parallel tools. It distinguishes itself from siblings like ask_pipeworx by specifying use cases and limitations.

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 use deep_research (broad/multi-part questions over structured data) and when to use alternatives (ask_pipeworx for single lookup or current news, and for free tier if not signed in). Also details depth options and their behaviors.

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, so the safety profile is covered. The description adds value by detailing the return format (names, descriptions, full input schemas with examples) and stating results are ready to call directly. No contradictions.

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

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

The description is concise (4-5 sentences), front-loaded with the core purpose, and every sentence serves a function: stating purpose, listing use cases, explaining return content, and giving invocation advice. No wasted words.

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

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

Given the tool's role as a discovery tool and the absence of an output schema, the description fully explains what the tool returns (top-N relevant tools with names, descriptions, and schemas). It covers purpose, when to call, and what to expect, making it complete for an agent to use effectively.

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 does not add significant meaning beyond the schema; it mentions example queries but those are also in the schema examples. Baseline 3 is appropriate as the schema already documents the parameters adequately.

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

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

The description clearly states the tool finds tools by describing the data or task, with specific verb ('Find') and resource ('tools'). It distinguishes from all sibling tools by being the only discovery tool, and explicitly lists many domains (SEC filings, FDA drugs, etc.).

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

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

Explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Also enumerates specific usage scenarios (SEC filings, financials, etc.) giving agents clear context when to invoke this tool over alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context: patents 'soft-fails until reactivated', news uses GDELT→GNews fallback, and it fans out across multiple sources. No contradictions with annotations.

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

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

The description is long but front-loaded with a summary of purpose and usage examples. It is well-structured with bullet points for return fields. While every sentence adds value, it could be slightly more concise without losing information.

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

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

Given no output schema, the description thoroughly explains return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and their sources. It covers the complexity of the tool and compensates for missing output schema.

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

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

Schema coverage is 100%, but the description adds important context: type is currently limited to 'company', value expects a ticker or zero-padded CIK, and names are not supported. This adds meaning beyond the schema's raw definitions.

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' and lists specific data sources and return fields (SEC EDGAR, XBRL, USPTO, news, GLEIF). It distinguishes itself from siblings like compare_entities and resolve_entity by emphasizing it is a holistic, one-call alternative to 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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies that names are not supported and directs users to use resolve_entity first if they only have a name, providing clear when-to-use and when-not-to-use guidance.

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

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

Description states 'Delete', matching destructiveHint=true. Annotations already provide destructiveHint and idempotentHint. No additional behavioral traits beyond what annotations offer, so adequate but not enriched.

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

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

Two sentences with no filler. First sentence states purpose, second provides usage guidelines. Perfectly concise and front-loaded.

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

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

Given simple single-parameter schema, annotations covering safety, and no output schema needed, the description is fully adequate. Mentions related tools ('remember' and 'recall') for context.

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

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

Schema coverage is 100% with a single 'key' parameter described as 'Memory key to delete'. Description adds no extra semantic meaning beyond the schema, so baseline score of 3.

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

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

Description clearly states 'Delete a previously stored memory by key.' with a specific verb and resource. It is easily distinguished from sibling tools like 'remember' and 'recall'.

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

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

Provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data'. Mentions pairing with 'remember' and 'recall', but does not explicitly state when not to use or name 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 destructiveHint as safe. The description adds value by detailing the process (fetches page, extracts title/description/key links, emits standard format) and noting output is a text blob. This goes beyond 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?

The description is only three sentences, front-loaded with purpose and audience, followed by process and use cases. Every sentence earns its place with no redundant information.

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

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

For a tool with 2 parameters and rich annotations, the description covers purpose, process, output, and use cases. It does not detail error handling or output format specifics, but given the known llms.txt standard and annotations, it is largely complete.

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

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

Schema coverage is 100% with both parameters described. The description adds meaning beyond the schema by explaining the output format (standard llms.txt markdown) and emphasizing 'any URL'. This provides context that enhances parameter understanding.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the resource and action. It distinguishes from siblings by focusing on generating the standardized file, whereas siblings like ai_visibility_check or scan_competitor_ai_presence likely check presence or scan.

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

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

The description explicitly lists three use cases (getting a client's site indexed, drafting for own project, auditing a competitor). It provides clear context for when to use, though it does not explicitly mention when not to use or direct to alternatives.

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

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

Annotations already indicate read-only, idempotent, etc. The description adds value by specifying the return content (balanced equation, cross-references) and background about Rhea. 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 three sentences, front-loaded with the purpose and return details. Every sentence adds value without 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 simple tool (1 param, no output schema, good annotations), the description covers purpose, return content, and background. However, the term 'keyless' is left unexplained, and error handling is not addressed, 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?

The schema already describes the id parameter with examples. The description repeats the examples but adds contextual background about Rhea. Since schema coverage is 100%, baseline 3 is appropriate; the description does not provide new 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 fetches a single Rhea reaction by its Rhea id, with examples. It distinguishes from the sibling 'search_reactions' which likely handles multiple reactions.

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 fetching a reaction by ID, but does not explicitly state when to use this tool versus alternatives like search_reactions. No when-not conditions or alternative tool names are given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds return field details and the ability to include inactive subscriptions, adding 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?

Two sentences, front-loaded with purpose, no wasted words. Excellent conciseness.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers what is returned, when to use, and the optional parameter behavior. Fully adequate.

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 include_inactive fully described. Description does not add new meaning beyond the schema. Baseline 3 is appropriate.

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

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

Clearly states 'List the caller's active subscriptions' with specific verb and resource, and distinguishes from sibling tools like subscribe/unsubscribe.

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

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

Provides explicit use cases ('review what you're monitoring before adding more' and 'find an id to cancel'), implying when to use it vs. subscribe/unsubscribe. Could be more explicit 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?

Discloses behavioral traits beyond annotations: rate limit, no quota impact, daily team review, roadmap impact. Annotations provide no such details, so description adds full value.

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

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

Every sentence is necessary and well-placed. Front-loaded with purpose, then usage, then behavioral notes. Concise yet comprehensive.

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 3 parameters (one with enum, one nested object) and no output schema, the description covers all needed info: when/why/how to use, limitations, and team process. Nothing essential is missing.

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

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

Schema coverage is 100%, but description adds extra value: for 'message' it specifies 1-2 sentences typical and 2000 char max, and for 'type' it reiterates enum meanings. Also adds context about not pasting prompts.

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: sending feedback about bugs, missing features, data gaps, or praise. It distinguishes itself from siblings because no other tool serves this feedback function.

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 specifies when to use (bug, feature/data_gap, praise) and what to avoid (do not paste end-user prompts). Also mentions rate limit (5 per identifier per day) and that it's free and doesn't count against quota.

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, idempotent, non-destructive. The description adds valuable behavioral context: data is self-aggregating from CF analytics-engine, no PII, and caching behavior (5min-1h). 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 only three sentences, front-loading the core function, then listing use cases, then technical details. Every sentence is informative and non-redundant with the schema or annotations.

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 read-only tool with one optional parameter and no output schema, the description covers purpose, usage guidance, parameter semantics, and important behavioral traits (no PII, caching). It is fully adequate for an agent to correctly select and invoke the tool.

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

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

The schema already describes the single parameter with enum and explanation. The description reinforces the trade-off between windows ('shorter windows surface what's hot right now; longer windows show steady-state demand'), adding meaningful guidance beyond the schema. With 100% schema coverage, baseline is 3, but the added context justifies a 4.

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

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

The description clearly states it returns top tools, packs, and call volume over a window, with three explicit use cases. This distinguishes it from siblings like discover_tools or ask_pipeworx, which have different purposes.

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 three concrete scenarios for when to use the tool (discovering hot data sources, confirming canonical choice, seeing alignment) and explains window selection trade-offs. However, it does not explicitly mention when not to use it or compare to alternative tools, though the sibling list and context signals provide some implicit guidance.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and no destructive hint. The description extensively details algorithmic behavior: monotonicity violations, partition-sum checks, semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder slugs), fill check (CLOB depth analysis), and response structure. No contradiction with annotations; adds significant behavioral context.

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

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

The description is well-structured with bold headers and bullet-like details, front-loading the core purpose. While comprehensive, it is somewhat lengthy; however, every sentence adds value. Minor redundancy could be trimmed, but overall 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?

Despite no output schema, the description covers all critical aspects: three usage modes, detailed algorithm steps (monotonicity, partition check, semantic anchor, partition filter), fill check with live depth, and reference to sibling tool for custom sizing. It fully equips an AI agent to understand behavior and 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 'event' (slug/URL) and 'topic' (seed question). The description adds deep meaning: for 'event' it explains walking child markets and checks, for 'topic' it describes cross-event searching and flattening. Also explains default behavior with no args, going far beyond schema definitions.

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 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks,' providing a specific verb+resource+method. It distinguishes the tool from siblings listed (e.g., polymarket_edges, polymarket_fill_risk) by detailing unique arbitrage detection techniques.

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 three modes: no args for trending_scan, 'event' for specific markets with examples like 'fed-decision-may-2026', and 'topic' for cross-event scanning with seed questions. Recommends 'event' for specific markets and explains when cross-event mode is useful, providing clear context for selection.

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

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

The description provides extensive behavioral details beyond the annotations (readOnlyHint, openWorldHint, etc.), including caching at KV level keyed on knobs, response structure with diagnostics, and detailed explanations of model families, edge calculations, and filter knobs. This fully informs the agent of the tool's behavior.

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

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

The description is lengthy and detailed, which is justified for the complexity, but it lacks conciseness. Multiple paragraphs and run-on sentences could be streamlined without losing value.

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

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

Given the tool's complexity (9 parameters, no output schema, nested concepts), the description is remarkably complete. It explains model families, edge fields, caching, diagnostics, and exclusions (e.g., Fed bets), providing everything an agent needs to use the tool effectively.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds some additional context for parameters like slippage_pp (mentioning Polymarket fees) and min_liquidity, but does not significantly enhance understanding beyond the schema descriptions.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It uses a specific verb-resource combination and distinguishes its purpose from sibling tools like polymarket_arbitrage and polymarket_kalshi_spread, though not explicitly named.

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 positions the tool for 'what should I bet on today' and explains that agents can discover opportunities without paging hundreds of markets. It provides clear usage context but does not explicitly state when not to use it or compare with siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false. The description adds important behavioral context: that data is built from daily snapshots, decay is computed from daily closes, history is bounded by 60-day TTL, and snapshots are written on cache-miss. No contradictions.

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

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

The description is thorough and well-structured with sections (RESPONSE, LIMITS), but it is lengthy and includes verbose sentences (e.g., 'the latter is wide for a reason nobody is willing to take') that could be trimmed without losing meaning.

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

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

With no output schema, the description fully explains the return structure: `tracked[]`, `expired[]`, and `snapshot_dates[]` with field meanings (trend, decay_pp_per_day, lifespan_days, etc.). It also covers the history limits and data gaps, making it self-contained for an AI agent.

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

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

Schema coverage is 100% with descriptions for both params. The description adds value by clarifying that `days` has a default of 14 and max 30 (aligned with schema clamp), and that `window` refers to 'snapshot family' with a default of '1wk', providing user-oriented context 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 provides 'edge persistence and decay telemetry' and answers the specific question 'how long has this edge existed and is it shrinking?', distinguishing it from siblings like `polymarket_edges` which likely gives current edges.

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

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

The description provides rich context for when to use this tool, explaining the significance of edge age with an example ('a fresh wide edge and a 3-week-old wide edge are different trades') and noting limits like 60-day TTL and decay from daily closes. However, it does not explicitly contrast with sibling 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?

Given annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already indicate a safe, read-only operation, the description adds significant behavioral context: it checks live order-book depth, walks the ladder, returns specific fields like top_of_book, vwap_fill_price, slippage, and describes risks 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 sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS...), making it scannable. Some sentences are complex, and there is redundancy (e.g., repeating modes), but overall it earns its length given tool 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?

The description covers the tool's behavior, modes, outputs, and risks comprehensively, especially given no output schema. It explains return values and edge cases like thin legs and forced directional risk. Minor gaps: no explicit error handling or timeout info, but sufficient for most use cases.

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

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

Schema description coverage is 100% (all 4 parameters described), but the description adds substantial meaning beyond the schema: it explains the difference between single-market and basket modes, interprets size_usd as settlement notional in basket mode, and describes default behavior for side. This enriches the agent's understanding.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It specifies two distinct modes (single-market and basket/partition mode) and lists concrete outputs, distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly stating when to use it.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale (theoretical overround not capturable, partial fills create directional risk) and implies when not to use other tools.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds rich behavioral context: two modes, response structure (leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and explanations of when spreads are meaningful vs meaningless. 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 well-structured: high-level purpose, then modes, response, safety fields. Every sentence contributes unique information. While somewhat lengthy, the complexity of the tool justifies the detail. Could be slightly tightened but remains effective.

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

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

Given the tool complexity (cross-venue spread with compatibility checks and no output schema), the description is thorough. It covers all key aspects: modes, parameter usage, response fields (top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters), and practical caveats. The agent can correctly invoke 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 each parameter described. Description adds significant value by explaining the two usage modes (topic list vs custom tickers), listing all 10 topic shortcuts, and providing concrete examples (e.g., 'KXFED-26OCT', 'fed-decision-in-june-825'). This goes beyond basic 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?

Clear verb ('cross-venue spread') and resource ('Kalshi and Polymarket for same resolving question'). Explicitly distinguishes two modes (topic shortcuts and explicit tickers) and differentiates from siblings like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

Clearly explains when to use (to compare same-outcome prices across venues) and when not (when compatibility_warning fires, e.g., non-equivalent bet shapes or temporal misalignment). Provides context on pre-mapped topics not always being tradeable, but does not explicitly name alternative sibling tools for similar tasks.

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

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

Annotations already declare read only, idempotent, and non-destructive behavior. The description adds useful context: scoping to identifier (anonymous IP, BYO key hash, account ID) and the behavior when key is omitted. This adds value beyond annotations, though could include more details like limits.

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

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

Three sentences, front-loaded with the core purpose. Every sentence adds value with no wasted words. Structure is clear and easy to parse.

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

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

The tool is simple with one optional parameter and no output schema. The description covers the retrieval and listing functionality, scoping, and relationship to sibling tools. It is fully complete for an agent to understand when and how to use it.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the dual behavior (retrieve vs list) and the context of using the key. It goes beyond the schema's description by providing usage examples and the scoping concept.

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 'retrieve' and 'list', clearly stating the dual behavior of getting a value by key or listing all keys. It also distinguishes from sibling tools '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?

The description provides explicit context for when to use the tool: 'to look up context the agent stored earlier... without re-deriving it from scratch.' It mentions pairing with 'remember' and 'forget'. However, it does not explicitly state when not to use it, leaving a minor gap.

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 describes that setting mark_read:true flags events as read, which is a state change. However, annotations set destructiveHint=false, contradicting this behavioral trait. This inconsistency is flagged as an annotation contradiction.

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

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

The description is four sentences, front-loaded with purpose, then return data, parameters, and usage guidance. 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 no output schema, so the description adequately explains return structure (source, citation_uri, raw payload) and parameter effects. Missing details about pagination beyond limit, but overall sufficient for the complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing examples (type 'sec_8k', ISO timestamp for since, and explanation of mark_read behavior), enhancing understanding beyond the schema.

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

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

The description clearly states it pulls fired events from a subscription feed, returning recent alerts with source, citation_uri, and raw payload. It specifies filtering by type and since, and the mark_read feature. While it does not explicitly distinguish from sibling tools like 'recent_changes', the verb 'pull' and resource 'fired events' are specific enough.

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 usage context, noting that polls work fine and mentioning an alternative direct API endpoint for scripts and dashboards. It does not explicitly exclude scenarios or list alternatives, but the guidance is clear and practical.

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

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

Discloses fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO with soft-fail, and details on since parameter formatting; adds significant context beyond the readOnlyHint and idempotentHint 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?

Single paragraph with front-loaded purpose and efficient detail, though slightly long; every sentence adds value.

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

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

Covers sources, fallback behavior, input formatting, return structure, and sibling alternative; 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%, baseline 3; the description adds usage examples for since and confirms type restrictions, providing meaningful added context.

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

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

The description clearly states the tool provides a change feed for a company over a recent window using multiple sources, and distinguishes it from entity_profile for static data.

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

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

Includes example natural language queries, explains when to use the tool (for recent changes), and explicitly directs to use entity_profile instead for static profile.

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 (idempotentHint=true, destructiveHint=false), the description adds key behavioral details: key-value storage scoped by identifier, persistence differences for authenticated vs anonymous users (24 hours), and pairing with recall/forget. 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 four sentences, front-loaded with purpose, and contains no redundant information. It could be slightly more structured (e.g., separating when-to-use from behavior), but overall 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 the simple tool (2 params, no output schema), the description is complete: it explains purpose, usage, storage details, persistence, and related tools. No gaps remain for an agent to safely use this tool.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces the key-value pair concept but does not add new meaning beyond the schema's parameter descriptions. The examples are helpful but not essential.

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 clear verb+resource ('Save data the agent will need to reuse later') and distinguishes itself from siblings by mentioning recall and forget. It also provides specific examples of what to save (resolved ticker, address, etc.), making the purpose unambiguous.

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

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

The description explicitly says when to use ('when you discover something worth carrying forward') and gives concrete examples. It points to sibling tools for retrieval and deletion, but does not explicitly state when not to use, which is a minor gap.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as safe. The description adds valuable internal behavior: 'cascades through several lookup endpoints internally' and 'replaces 2-3 manual lookups', which helps the agent understand the tool's internal complexity. 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 moderately verbose but well-structured with examples and clear sections. It front-loads example queries and then lists supported types. Some redundancy exists (e.g., repeating 'returns'), but overall efficient for the amount of information.

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

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

Given the absence of an output schema, the description fully explains the return values for both entity types, including specific fields and citation URIs. It also covers input variants. No gaps remain for an agent to understand what the tool does and what it returns.

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

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

Schema coverage is 100%, and the description adds significant detail beyond the schema: explains the return format for each type (e.g., company returns ticker + CIK + company_name + citation URI) and the accepted input varieties (ticker, CIK, name). This fully compensates for the lack of output schema.

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

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

The description clearly states it resolves user-spoken names to canonical identifiers, with specific examples like 'What's the ticker for…'. It distinguishes from siblings by noting 'Use FIRST whenever you have a name but need an ID' and listing supported types (company, drug).

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

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

Explicitly says when to use: 'Use FIRST whenever you have a name but need an ID.' Also notes that it replaces 2-3 manual lookups. Does not explicitly state when not to use, but the context with siblings implies alternatives (e.g., if you already have an ID). Clear enough for an agent.

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 that it internally calls ai_visibility_check, ranks results, and returns score/confidence/signal density per entity.

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

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

Three sentences, front-loaded with purpose. No fluff; every sentence adds information.

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

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

Given 4 parameters (all explained), no output schema, but description covers return structure. Sufficient for agent to understand input/output and behavior.

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

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

All 4 parameters documented in schema (100% coverage). Description adds value: explains entities[0] is treated as subject for narrative, and describes relationship between models and _apiKey.

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

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

Description clearly states the tool compares AI visibility across entities, probes with ai_visibility_check, ranks by score, and surfaces most/least recognized. Distinct from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

Explicitly mentions use case: competitive AI-marketing audits, with example question. No when-not-to-use or alternative tools explicitly stated, but context is clear enough for agent to infer.

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 indicating readOnly, idempotent, and non-destructive, the description adds critical behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. 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 but front-loads the core purpose and use cases. Every sentence adds value, though it could be slightly more structured (e.g., bullet points) for readability. No wasted words.

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

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

Given no output schema, the description fully details return fields: summary block with keys like license, bundle sizes, has_esm, etc., plus per-advisory details and alternative versions. It also covers partial failure behavior. Complete for a two-parameter composite 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% for both parameters. The description adds value by noting that scoped packages (e.g., @types/node) are accepted and that version defaults to the latest published when omitted, which goes beyond the schema 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 it is a composite check for deciding whether to add an npm package, combining deps.dev and bundlephobia data. The verb 'scan' and resource 'dependency' are specific, and the tool is distinct from siblings like scan_competitor_ai_presence or other research 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 when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me". It also specifies limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', providing clear context for 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, openWorldHint, idempotentHint, and destructiveHint. The description adds value by noting that no API key is required ('Keyless') and specifying the output format (balanded plain-text reaction equation plus EC/ChEBI cross-references). 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 two focused sentences with no redundant information. It front-loads the context (Rhea, referenced by UniProt/KEGG) and then states the search capabilities and outputs efficiently.

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 (2 params, no output schema, rich annotations), the description covers purpose, input types, and output format adequately. The absence of an output schema is compensated by describing the return value. Slight gap: no mention of pagination or result order.

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 the schema by listing example query types (compound name, ChEBI id, EC number, etc.) and tying them to the Rhea database, which helps the agent understand valid inputs.

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 searches the Rhea database for biochemical reactions by various criteria and returns balanced equations with cross-references. It is specific about the resource and action, though it does not explicitly differentiate from the sibling tool 'get_reaction', which likely gets a single reaction details.

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?

No explicit guidance on when to use this tool versus alternatives like 'get_reaction' or when not to use it. The description lacks context for decision-making, such as prerequisites or limitations.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds rich behavioral details (embedding model BGE-base-en, 500-char overlapping windows, 200K char cap with truncation flag, return of passages with offsets and similarity scores) that go well beyond annotations. No contradictions.

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

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

The description is two well-structured sentences: the first sentence focuses on the core function and second sentence elaborates on use case and details. Every sentence earns its place without fluff.

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

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

Despite no output schema, the description fully explains return values (passages with offsets and scores), behavioral constraints (200K char cap, truncation), and use case. It is 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 baseline is 3. The description adds meaning by explaining that 'query' should be natural language with examples, and that results include character offsets and similarity scores, which enhances understanding beyond the schema descriptions.

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

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

The description clearly states the tool does semantic search inside a fetched record, with specific examples (SEC 10-K, article) and distinguishes from the sibling tool ask_pipeworx_grounded by explaining the pairing pattern.

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

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

The description explicitly states the use case ('when the record is too big to cram into the prompt') and recommends pairing with ask_pipeworx_grounded. However, it does not explicitly state when not to use this tool.

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

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

Annotations indicate destructiveHint=false, idempotentHint=true, readOnlyHint=false. Description adds: returns new subscription ID, requires OAuth, constraints on delivery (SMS cap, phone verification, webhook auto-disable after 10 failures), and type-specific parameter details. 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 a single paragraph but well-structured with clear separation of types and delivery. It is concise yet comprehensive; every sentence adds value. Could benefit from bullet points for readability, but current structure is effective.

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

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

No output schema provided, but description states return is the subscription ID. Covers all three parameters (type, params, delivery) in depth, including constraints, required fields, and examples. For a tool with nested objects and enums, the description is fully sufficient for 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%, but description adds meaning: for sec_8k, explains items codes; for fred_series, shows series_id; for delivery, details SMS cap and webhook HMAC signing. These examples and constraints go beyond schema descriptions, making parameters more understandable.

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 'Create a proactive monitoring subscription to a live-data event stream' and notes it returns a subscription ID. Distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by emphasizing proactive monitoring and subscription creation.

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

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

Explicitly states prerequisite: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' Provides examples for each type with parameters, indicating when to use each. Does not explicitly contrast with list_subscriptions or unsubscribe, but the context signals (sibling tools) imply differentiation.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds value by explaining the output structure (category-bucketed example questions with tool/argument shapes) and usage flexibility (full spread vs topic focus). No contradictions with annotations.

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

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

The description is a single paragraph that front-loads common queries and includes all essential details. It could be slightly shorter, but every sentence serves a purpose (aliases, output description, argument usage, usage guidance). No wasted words.

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

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

For a simple tool with 0 required parameters and a well-annotated schema, the description is fully complete. It covers purpose, when to use, arguments, output structure, and provides enough context for an AI agent to invoke it correctly. No output schema is needed given the textual description of returns.

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

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

The schema has 100% coverage for the single optional parameter 'topic' with a clear description. The description reinforces the parameter's purpose and lists example values, but adds little beyond the schema. The baseline of 3 is appropriate since schema already handles the semantics.

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

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

The description clearly defines the tool as the onboarding entry point, listing several natural language queries it answers ('What can I ask Pipeworx?', 'give me ideas', etc.) and specifying it returns category-bucketed example questions. It distinguishes itself from siblings like discover_tools and ask_pipeworx by focusing on introductory guidance and tool usage examples.

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

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

The description explicitly states when to use this tool: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also provides guidance on arguments (optional topic) and hints at alternatives (meta-tools like ask_pipeworx, entity_profile).

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, the description reveals that the row is deactivated (not deleted) and explains the availability of historical events via recent_alerts. This adds valuable context about the tool's side effects and non-destructive nature.

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, no wasted words. The action, restriction, and consequence are front-loaded and clear.

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

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

For a one-parameter tool with no output schema, the description fully explains ownership enforcement, the effect on data, and preservation of history. It is complete and sufficient for correct usage.

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 does not add further details about the 'id' parameter beyond what the schema provides ('Subscription id (uuid) returned by subscribe').

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

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

The description clearly states the action ('cancel'), resource ('subscription'), and method ('by id'). It effectively distinguishes itself from siblings like 'subscribe' and 'list_subscriptions'.

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

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

The description provides clear context: 'Ownership is enforced — you can only cancel your own subscriptions.' It implicitly guides when to use (own subscriptions) but does not explicitly mention when not to use or suggest alternative tools.

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

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

Annotations already indicate a safe, read-only, idempotent operation. The description adds substantial behavioral context beyond annotations, such as the verdict types, extracted structured form, actual value with citation, and percent delta. 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 well-structured with usage examples, supported domain, and output details. It is slightly lengthy but every sentence adds value, and it is front-loaded with key usage patterns.

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

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

Given the tool has only one parameter, no output schema, and the description explains return values and scope, it is fully complete. Annotations cover safety and behavior adequately.

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

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

The input schema already describes the claim parameter with examples. The description adds further meaning by specifying the types of claims supported (company-financial via SEC EDGAR+XBRL), enhancing understanding beyond the schema.

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

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

The description clearly states the tool's purpose as natural-language claim verification against authoritative sources with specific examples. It does not explicitly differentiate from sibling tools but implies a specialized role by stating it replaces multiple sequential calls.

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

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

The description explicitly advises using the tool whenever the agent needs to check factual correctness. It also specifies the supported domain (company-financial claims for public US companies), providing clear context for appropriate usage.

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