Corporate Apology

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

The description adds behavioral context beyond annotations: it specifies scoring range (0-100), per-model output fields, and API key passthrough. Annotations already declare readOnlyHint and idempotentHint, which are consistent. No contradiction, and the description complements annotations with helpful details.

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

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

The description is a single paragraph of 4 sentences, front-loaded with the core action and result. Every sentence adds value (purpose, default model, API key condition, return format, use cases). No wasted words, appropriately sized.

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

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

Despite no output schema, the description explains return format (per-model {score, confidence, signals, raw_response} + combined view). With 4 parameters all documented and clear annotations, the description is sufficient for an agent to invoke the tool correctly.

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

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

With 100% schema coverage of parameters, the description adds meaningful context: it explains the default model for 'models', optionality and use case for '_apiKey', and disambiguation purpose for 'context'. This goes beyond the schema descriptions and helps the agent select appropriate values.

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: probing LLMs for knowledge about a business/brand/product/topic and scoring visibility. It uses specific verbs ('probe', 'score') and identifies the resource (LLMs), distinguishing it from sibling tools like 'scan_competitor_ai_presence' which focuses on competitors.

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

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

The description provides explicit usage scenarios such as 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It also explains when to use different models (default free model vs. requiring API key). However, it does not explicitly state when not to use this tool or compare it to similar 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?

The description adds significant context beyond annotations (readOnlyHint, idempotentHint) by detailing routing to 3,751 tools, sourcing from 886 verified sources, and returning structured answers with stable citation URIs. No contradictions.

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

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

The description is well-structured with key guidance upfront, but it is slightly verbose due to extensive domain lists and examples. Most sentences contribute value.

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

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

Despite no output schema, the description adequately explains return format (structured answer with citations). It could mention potential limitations or error handling, but overall sufficient for a query tool.

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

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

Schema coverage is 100% with all parameters being aliases for 'question'. The description explains these aliases and provides usage examples, adding value beyond the schema definition.

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 answering factual questions using structured data from numerous sources. It lists specific domains (SEC filings, FDA data, etc.) and provides concrete example queries, distinguishing it from siblings like 'deep_research' and 'bet_research'.

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

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

Explicitly recommends preferring this tool over web search for factual questions and lists appropriate use cases with examples. However, it does not explicitly state when not to use it or name alternative tools from the sibling list.

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

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

Despite strong annotations (readOnlyHint, idempotentHint), the description adds significant behavioral context: it extracts answer only from tool result, returns explicit refusal reasons, and details the response structure. No contradiction with annotations.

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

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

Description is front-loaded with core purpose, then covers behavior, response, refusal reasons, and usage guidance. Every sentence adds value, no redundancy.

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

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

Despite no output schema, the description fully covers response structure, refusal reasons, cost, and when to use. Complete for a complex tool with many sibling tools.

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

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

Schema coverage is 100% with all parameters described as aliases for 'question'. The description adds minimal extra meaning beyond the schema (e.g., natural language), so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode for high-stakes reads. It uses specific verbs and resource ('ask Pipeworx — Grounded'), distinguishes from sibling ask_pipeworx by highlighting extraction-only behavior and response format.

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

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

Explicitly tells when to use (quoted/cited/acted on answers) and when not (casual lookups, prefer ask_pipeworx). Also explains cost trade-off (extra LLM call), providing clear guidance.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds extensive behavioral context: fan-out behavior, resolver contract with confidence levels, parent event extractor, news fields with fallback handling, safety short-circuits for low confidence and closed markets, wide-spread note, and resolution-rule risk. 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 quite long (multiple paragraphs) with detailed sections, which may overwhelm an agent. It is front-loaded with the main purpose and well-structured with headers, but some technical details (e.g., specific data sources) could be condensed. Every sentence adds value, but brevity is sacrificed.

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

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

Given the tool's complexity (multi-source research, safety checks, resolver logic, multiple response fields) and the absence of an output schema, the description provides nearly complete coverage: it explains market_match_confidence, parent_event, news fallbacks, cancellation rules, and blocking conditions. No major gaps.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds meaning beyond schema by explaining acceptable input formats (slug, URL, question text), the difference between 'quick' and 'thorough' depth, and the rationale for include_raw. The schema examples are complemented by narrative 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 specifies the tool researches a Polymarket bet by pulling data, accepts slug/URL/question text, and returns evidence packet + market-vs-model comparison. It distinguishes from siblings by stating 'use for should I bet on X' and providing examples, clearly differentiating from polymarket_edges and similar tools.

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

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

The description explicitly lists use cases like 'should I bet on X', 'what does the data say about Y', and 'is there edge in Z'. It provides examples of fan-out for different bet types, giving clear context. However, it does not explicitly state when NOT to use this tool versus alternatives, though the context is strong enough.

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

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

Description adds rich behavioral context beyond annotations: data sources (SEC EDGAR/XBRL, FAERS), specific financials and counts, handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. Annotations already indicate safety, so description enhances transparency 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 dense but well-structured, front-loading usage patterns. Slightly long due to detailed behavioral info, but every sentence adds value. Could be trimmed slightly, but still effective.

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

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

Given the tool's complexity (two entity types, multiple data points per type), the description covers all key aspects: what data is returned, how it's sorted, citation URIs, and when to prefer this tool. No output schema needed.

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

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

Schema covers both parameters (type, values) at 100% coverage. Description adds meaning: explains what each type returns, format for values (tickers/CIKs vs drug names), and the 2-5 range, going beyond the schema's enum and basic 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 uses strong verbs like 'compare', 'rank', 'head to head' and clearly states it performs side-by-side comparison of 2-5 companies or drugs. It distinguishes itself from siblings like entity_profile (single entity) and search_within (different purpose).

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and gives example queries. It does not explicitly list when not to use, but the context strongly implies it is only for multi-entity comparisons.

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

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

The description discloses the tone control via sincerity level and the return format ('ready-to-use apology text'), adding value beyond the annotations. Annotations indicate readOnlyHint=true and idempotentHint=true, which are consistent with a generation tool that has no side effects.

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

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

The description is concise with three sentences, no redundant words, and front-loads the purpose. Every sentence contributes 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 simplicity and the presence of an output schema, the description adequately covers the purpose, key parameter, and return type. It could mention that the apology is a template, but the output schema likely handles details.

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

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

The description adds some meaning for the sincerity parameter but contains an error: it lists 'defensive' as an option, while the schema enum includes 'performative', 'genuine', 'legal', 'pr', 'none'. This misleads the agent. It does not compensate for the 40% schema coverage, as other parameters (medium, audience) are not explained.

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 corporate apology statement, specifies the key parameter (sincerity level) and its role in controlling tone, and mentions the return type. It is distinct from the listed sibling tools.

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

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

The description explicitly says when to use the tool (to generate an apology for a specific offense) and mentions the sincerity parameter for tone control. It does not discuss when not to use it or alternatives, but the context is clear given the lack of related 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds specifics: returns 'verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citation', 'explicit gaps[]', 'facts arrive pre-verified', and 'structured findings packet.' No contradictions.

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

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

Description is well-structured with purpose, mechanism, usage, prerequisites, output, timing. Slightly verbose but each sentence adds value. Could be tightened slightly.

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, description covers purpose, behavior, parameters, usage context, prerequisites, timing, and output structure. Very complete for a complex tool.

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

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

Schema coverage is 100%. Description adds meaning: depth values 'quick=3, standard=5, thorough=8' and that thorough requires paid plan. Clarifies question is 'Broad/multi-part is fine.'

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 'Grounded multi-source research in ONE call' and explains the decomposition and parallel routing process. It distinguishes itself from sibling tool 'ask_pipeworx' (single lookup).

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 instructions: 'Use for broad or multi-part questions' and contrasts with 'ask_pipeworx for single lookups.' Also includes prerequisites: 'Requires a Pipeworx account' and 'depth:thorough requires a paid plan.'

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by stating that the tool returns 'the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that 'each result is ready to call directly, no second schema lookup needed.' This informs the agent of the result format and readiness.

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 mostly concise, starting with a clear statement of purpose and then listing examples. It could be slightly more front-loaded, but every sentence serves a purpose. It is not overly 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?

For a discovery tool with 6 parameters (1 required) and no output schema, the description sufficiently explains what the tool returns and how to use it. It lacks details like pagination or error handling, but the core functionality is well-covered.

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

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

The input schema covers all 6 parameters with 100% description coverage. The description mentions that 'query accepts task, q, description, search as aliases,' which is also present in the schema. Therefore, the description adds little semantic value beyond the schema, warranting a baseline score of 3.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides a long list of example domains and explicitly differentiates from siblings by saying 'Call this FIRST when you have many tools available and want to see the option set.'

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 the tool: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear guidance on when to invoke it.

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

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

Annotations already indicate safe read-only, open-world, idempotent behavior. The description adds significant context: fans out across multiple sources, details return fields (cik, filings, fundamentals, patents, news, LEI), mentions soft-fail for patents due to API sunset, and describes fallback behavior. No contradiction with annotations.

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

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

The description is thorough but still efficient. It front-loads with common queries, then details the behavior and return structure. Every sentence adds value, though a slight condensation would improve conciseness 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 explains return values adequately: lists specific fields and sources, mentions limits (up to 5 filings), and notes soft-failures. It could mention overall response size or pagination, but it provides a complete picture for a complex aggregator 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 adds value by reinforcing that only ticker or zero-padded CIK are valid, explicitly stating 'names not supported (use resolve_entity first if you only have a name)', which clarifies schema intent and links to a sibling tool.

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: 'full cross-source profile of a US public company in ONE parallel call'. It uses specific verbs like 'Tell me about' and 'research', and distinguishes from the sibling tool 'resolve_entity' by noting that names are not supported here.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also tells when to use resolve_entity first if only a name is available, providing clear alternatives.

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

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

Annotations already declare destructiveHint and idempotentHint. Description adds context about clearing sensitive data and stale context, enriching 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.

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

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

For a simple single-parameter destructive tool, description covers purpose, usage, and behavioral traits completely.

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

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

Schema coverage is 100% with description 'Memory key to delete'. Description adds no extra meaning beyond what schema provides.

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

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

Description clearly states 'Delete a previously stored memory by key.' Verb+resource pairing is specific and distinguishes from siblings 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?

Explicitly tells when to use ('context is stale, task is done, clear sensitive data') and mentions related tools ('Pair with remember and recall').

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

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

Description adds value beyond annotations by detailing the process (fetches page, extracts title/description/key links, emits standard markdown) and output format (single text blob), while annotations already indicate read-only, idempotent, non-destructive 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?

Three sentences, front-loaded with purpose, process, and use cases. No redundant or superfluous text.

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

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

For a simple tool with 2 parameters and rich annotations, the description covers input, output, and usage context fully, with no gaps.

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

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

Schema description coverage is 100% and the description does not add new parameter-specific information beyond what's in the schema (e.g., default/max values are already documented in schema).

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

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

Description explicitly states the verb 'generate' and resource 'llms.txt file' for any URL, and distinguishes from siblings by focusing on a specific output format and use cases like AI crawler indexing.

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 clear use cases (client site indexing, drafting own project, auditing competitors) but does not explicitly state when not to use or mention alternatives, though sibling tools are numerous and distinct.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. Description adds return field details but no extra behavioral constraints. Adequate but not exceptional.

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 wasted words: first provides purpose and output, second gives usage context. 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 one optional parameter, no output schema, and annotations covering behavior, the description is nearly complete. Minor omission: no mention of default ordering or pagination, but not critical for this simple list tool.

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

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

Schema covers the single optional parameter (include_inactive) with a full description. The tool description adds no further parameter details beyond the schema, matching the baseline for high schema coverage.

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

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

Clearly states the tool lists the caller's active subscriptions and enumerates return fields. While not explicitly contrasting with siblings, the purpose is unambiguous and 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?

Provides explicit guidance: use it to review subscriptions before adding more or to find an ID for cancellation. Missing alternatives or when-not-to-use, but context is helpful.

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 no destructive behavior, but description adds critical behavioral details: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, and team reads daily. 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?

Highly concise and well-structured. The purpose is stated immediately, followed by usage guidelines, constraints, and additional notes. No unnecessary words; every sentence contributes 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?

Given the tool's simplicity (feedback submission), the description covers all needed context: purpose, usage, parameter guidance, behavioral notes, and constraints. No output schema is expected for such a tool.

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

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

Schema coverage is 100% with detailed descriptions, but the description adds value by explaining the enum values in context and reiterating the need for specificity. It goes beyond the schema by providing concrete examples and length limits.

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 to the Pipeworx team about bugs, missing features, or praise. It distinguishes itself from sibling tools (e.g., ask_pipeworx, discover_tools) by focusing on reporting issues rather than querying or exploring.

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

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

Provides explicit when-to-use scenarios (bug, feature/data_gap, praise) and clear guidance on how to write the message (describe in terms of Pipeworx tools/packs, avoid pasting end-user prompts). Also notes rate limits (5/day) and that it's free with no quota impact.

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

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

Beyond annotations (readOnlyHint, etc.), the description adds detailed behavior: data source (CF analytics-engine), no PII, and caching policy (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?

Three concise sentences: first defines output, second lists use cases, third adds technical details. Every sentence earns its place; no fluff.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers return values, use cases, privacy, and caching. No gaps remain.

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

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

The parameter 'window' is fully described in the schema (100% coverage). The description adds semantic nuance: shorter windows highlight hot trends, longer windows show steady-state demand, enriching the enum values.

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 what the tool does: returns top tools, top packs, and total call volume over a recent window. It distinguishes itself from sibling tools like discover_tools and ask_pipeworx by focusing on trending usage by other agents.

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

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

The description explicitly lists three specific use cases: discovering hot data sources, confirming canonical tool choice, and checking use case alignment. This provides clear when-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?

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds significant behavioral context: the fill check, semantic anchor, partition filter, and constraints on when signals are actionable (e.g., realizable_edge_pp <= 0 means do not trade). No contradictions noted.

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

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

The description is long but well-structured with clear sections (REQUIREMENT, modes, checks, response, fill check). It is front-loaded with the critical dependency. Some redundancy is present but does not detract from clarity. 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?

Given no output schema, the description thoroughly explains the response structure (opportunities array, partition_check, fill check). It covers both modes, validation checks, and references sibling tools for deeper dives. The agent has sufficient information to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining that event is for a specific market slug and topic for a seed question, provides examples, and clarifies the 'at least one required' constraint. This adds value beyond the schema.

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

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

The description clearly states that the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (single-event and cross-event) and explicitly compares to sibling tools like polymarket_fill_risk.

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 'REQUIRES one of event or topic — call with no args fails', recommends event mode for specific markets and topic mode for cross-event scanning, and mentions that cross-event mode catches patterns single-event misses. It also directs to polymarket_fill_risk for custom sizing.

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

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

Annotations already confirm read-only, open-world, idempotent, and non-destructive behavior. The description adds extensive behavioral details: 1-hour KV caching, output structure with segments and diagnostics, filter knobs, and even explains that partition arbs always return zero Kelly at parent level. 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 very long and includes detailed model family explanations (e.g., lognormal barrier, GDELT ratios) that may be excessive for a tool description. It is structured with sections (overview, segments, knobs, response) and front-loads the purpose, but could be more concise.

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

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

Given 9 parameters, no output schema, but rich annotations, the description fully explains the output structure (by_segment, diagnostics, fed_candidates), caching behavior, and how to interpret empty segments. It provides all necessary context for an AI 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?

Input schema has 100% coverage with detailed descriptions for all 9 parameters, so baseline is 3. The main description references these parameters in context (e.g., 'tradeable-edge knobs') but adds no additional meaning beyond what the schema already provides.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with the explicit use case 'what should I bet on today'. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on model-driven edge detection rather than pure arbitrage.

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

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

The description provides clear context for when to use this tool (discovering betting opportunities without paging markets) and includes notes on Fed bets being excluded with reasoning. However, it does not explicitly mention when not to use it or compare directly to alternatives like polymarket_arbitrage.

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

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

The description goes beyond annotations by detailing the response structure (tracked[], expired[], snapshot_dates[]), how decay is computed, and limitations like snapshot TTL and gaps. 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 dense paragraph that front-loads the core purpose and covers all necessary details. While effective, it could be more scannable with bullet points, but every sentence adds value.

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

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

With no output schema, the description fully explains the return format and limitations, making it complete for an agent to understand the tool's behavior and output.

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 default values and clarifies the window parameter as 'snapshot family', but does not provide additional semantic depth 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 measures edge persistence and decay, answering 'how long has this edge existed and is it shrinking?' It distinguishes from sibling polymarket_edges by focusing on historical telemetry rather than a single snapshot.

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 context on when to use this tool (to assess edge persistence) and contrasts with a fresh edge vs. an older edge. It also mentions history depth limits and snapshot gaps, giving clear usage boundaries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds crucial behavioral context: the tool is a risk check simulation (not actual execution), walks the ladder, returns specific verdicts, and warns about thin books and partial fills leading to directional risk. 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 clear mode headings and bullet points, but it is somewhat verbose, repeating return fields and examples. Every sentence adds value, but conciseness could be improved by reducing redundancy.

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

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

Given the moderate parameter count (4) and no output schema, the description fully covers both modes, return values (top_of_book, vwap_fill_price, slippage_pp, etc.), edge cases (thin_legs, forced_directional_risk), and usage constraints. It is complete for an AI agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100% with parameter descriptions. The description adds semantics beyond the schema: explains default values (size_usd default 1000, clamp 10–1,000,000; side defaults for basket auto based on partition sum), clarifies interpretation of size_usd per mode, and provides context for how parameters affect the check.

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

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

The description clearly states the tool performs a realizable-vs-theoretical edge check against live order-book depth. It distinguishes two modes (single-market and basket) and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use this tool 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?

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the reasoning (partial fills turn arbs into directional risk) and requires either market or event parameter.

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 and idempotent. The description adds extensive behavioral context: explains why spreads occur (participant pool differences), when they are meaningful (equivalent bet shapes), and details safety fields (compatibility_warning, temporal_alignment, skipped counters). No contradiction with annotations.

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

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

The description is well-structured with clear sections (modes, response, safety fields) and front-loads the main idea. It is somewhat verbose but every sentence adds necessary information; could be slightly condensed 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?

Despite no output schema, the description details response fields: leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters. This is sufficient for an agent to interpret results, though a formal schema would improve structure.

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 value by explaining the two parameter modes, the list of pre-mapped topics, and how explicit parameters override topics. This goes beyond the terse 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 it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic and explicit) and describes the response. No sibling tool does cross-venue spreads, so it is well-differentiated.

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 the two usage modes with examples and warns that pre-mapped topics may not be tradeable. It provides constraints like temporal alignment and compatibility warnings. However, it does not explicitly contrast with sibling tools like polymarket_arbitrage.

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 idempotentHint=true, and description aligns with 'retrieve'. It adds context about scoping to identifier (anonymous IP, BYO key hash, account ID), which goes beyond annotations. No contradictions.

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

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

Three sentences, no wasted words. Front-loaded with primary action, then usage guidance, then scope/pairing. Efficient 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 simple retrieval tool with one optional parameter and no output schema, the description covers purpose, usage, scope, and pairing. Missing return format details, but that is minor given the straightforward nature.

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

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

Schema description coverage is 100% and describes the parameter. The tool description adds value by explaining that omitting key lists all and providing examples of stored values (ticker, address, notes), 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?

Description clearly states the tool retrieves a stored value or lists keys, with specific verb 'Retrieve' and resource 'value previously saved via remember'. It distinguishes from sibling tools like '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?

Description explains when to use (look up context stored earlier) and gives examples (ticker, address, notes). It mentions omitting key to list all. However, it does not explicitly state when not to use or provide alternatives for listing vs specific retrieval.

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 correctly explains mark_read side effect (flags events as read), but annotations state readOnlyHint=true, implying no state modification. This is an annotation contradiction, forcing score to 1 per guidelines.

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

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

Front-loaded purpose, then details, then alternative. Three sentences with no fluff. Every sentence adds value.

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

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

Given 5 optional params, no output schema, and annotations covering safety, the description covers return fields, filtering, side effect, and alternative access. Thorough 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?

Adds context beyond schema: example for type ('sec_8k'), ISO format for since, default limit 50, and explanation of mark_read and unread_only. Schema coverage is 100%, but description enriches 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?

States clearly: 'Pull fired events from your subscription feed' with specific resource and action. Specifies return fields (source, citation_uri, raw event) and filtering options. Distinguishes from siblings like list_subscriptions by focusing on alerts.

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

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

Provides clear context: filter by type and/or since, use mark_read to manage read state, polls work fine. Mentions alternative access via URL. Lacks explicit when-not-to-use but sufficient guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds rich behavioral context: fan-out to three sources, GDELT→GNews fallback on rate limits, USPTO soft-fail, and output structure. No contradictions with annotations.

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

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

The description is comprehensive and front-loaded with use-case examples, but slightly verbose. Every sentence is meaningful, though some redundancy exists. Still highly efficient for the complexity covered.

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 multiple sources, fallback logic, and no output schema, the description is remarkably complete. It covers all key behaviors, parameter nuances, and provides an alternative tool reference. The output structure is summarized even without a full schema.

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

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

Schema coverage is 100%, and the description adds significant value: explains 'since' accepts ISO dates or relative shorthands with examples, clarifies 'type' is limited to 'company', and contextualizes 'value' as ticker or CIK. This goes well beyond the schema bare descriptions.

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

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

Description uses specific verbs ('change feed') and clearly identifies the resource (company) and sources (SEC, GDELT, USPTO). It distinguishes from sibling 'entity_profile' by stating when to use each, making purpose unambiguous.

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

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

Explicitly provides example queries ('What's new with X', 'latest on Y') and clarifies when to use the alternative 'entity_profile' instead. This gives clear guidance on when to invoke this tool versus others.

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

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

Annotations provide idempotentHint=true and destructiveHint=false. Description adds scoping by identifier, persistence differences (authenticated vs anonymous), and 24-hour retention for anonymous sessions. No contradiction.

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

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

Six sentences, front-loaded with main purpose. Every sentence adds unique information (persistence, scoping, related tools). No redundancy or fluff.

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

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

For a simple key-value save tool, the description covers purpose, usage triggers, storage behavior, scoping, persistence, and sibling tool relationships. No gaps remain.

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

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

Schema coverage is 100% with descriptions. The description adds value by providing concrete usage examples for keys and values (e.g., 'subject_property', 'user_preference') and clarifies value can be any text, slightly enhancing schema defaults.

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

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

The description clearly states the tool saves data for later reuse across conversations or sessions. It provides specific examples (resolved ticker, target address, user preference) and distinguishes from siblings like recall and forget.

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

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

Explicit when-to-use guidance: 'when you discover something worth carrying forward.' It also mentions pairing with recall and forget, giving clear context for alternatives. No misleading statements.

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 significant context: cascading internal lookups, specific returned fields per type ('ticker + 10-digit CIK + company_name' for company, 'RxCUI + ingredient + brand' for drug), and citation URIs. No contradiction.

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

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

Well-structured: starts with natural language examples, then core purpose, usage guidance, and type-specific details. Every sentence serves a purpose. Slightly verbose in the type descriptions 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 no output schema, the description adequately details return fields for both types. Annotations cover safety. It explains cascading behavior. Could mention error handling or edge cases (e.g., ambiguous names), but overall sufficient for a lookup tool.

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

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

Schema covers both parameters fully (100% coverage). The description adds value by clarifying accepted input formats (e.g., 'ticker (AAPL), CIK (0000320193), or name' for company) and explaining output behavior per type. This goes beyond the schema's basic descriptions.

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

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

The description explicitly states it resolves names to canonical/official identifiers, with concrete examples ('ticker for', 'CIK for', 'RxCUI for'). It distinguishes from siblings by focusing on ID lookup, not entity profiles or comparisons.

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?

Directly advises to 'Use FIRST whenever you have a name but need an ID.' This clearly signals when to invoke the tool. It also mentions replacing manual lookups, reinforcing its purpose. No explicit when-not-to-use, but the context is strong.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns score, confidence, and signal density per entity. This provides useful behavioral context beyond the annotations.

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

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

The description is three sentences long, front-loading the main function, then a use case, then the output format. 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?

Given no output schema, the description adequately describes the output (ranked list with score, confidence, signal density). It also explains the mechanism (probes each entity with ai_visibility_check) and constrains entity count (2-8). The annotations cover safety, so no further behavioral documentation is needed.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds semantic value by explaining that the first entity in the array is treated as the 'subject' for narrative purposes, which is not evident from the schema alone.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, ranking them by score. It distinguishes itself from siblings like 'ai_visibility_check' (single entity) and 'compare_entities' (generic comparison) by focusing on competitive AI-marketing audits.

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 a clear use case: 'Useful for competitive AI-marketing audits: does Claude know about us as well as our competitors?' It implies when to use it but does not explicitly list alternatives or conditions when not to use it.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: composite nature, bundlephobia measurement delay (5-30s), graceful degradation with sources_failed list, and ecosystem limitation.

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

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

The description is slightly long but well-structured, front-loading the composite check concept. Every sentence adds value, though could be tighter without losing clarity.

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

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

Despite no output schema, the description fully details the return structure (summary fields, per-advisory detail, links, alternative versions) and handles edge cases (partial failures, version delay). Complete for a 2-parameter tool with good annotations.

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 provides 100% coverage for both parameters. Description adds useful context: package accepts scoped packages (e.g., @types/node), version defaults to latest when omitted. Slightly enhances 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: a composite check for npm packages covering safety, popularity, size, and cost. It distinguishes itself from siblings (e.g., scan_competitor_ai_presence) and specifies the ecosystem scope (NPM only).

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

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

Explicitly provides usage guidance: 'Use whenever an agent asks...' with concrete examples. Also clarifies when not to use it (non-npm packages) and directs to an alternative tool (deps.dev:version).

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?

Adds technical details beyond annotations: embedding model, window size, character cap with truncation flag. No contradiction with annotations.

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

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

Concise, well-structured, front-loaded with purpose, followed by usage and technical details. 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 purpose, usage, return format (passages with offsets and scores), technical mechanism, and pairing with sibling. No output schema, but return info is described.

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 schema already documents parameters. Description adds example queries, providing extra context for the 'query' parameter.

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

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

Clearly states semantic search inside a fetched record, contrasting with sibling tools like 'ask_pipeworx_grounded' and noting the use case of saving context when a record is too large.

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 (when record too big for prompt) and how it pairs with 'ask_pipeworx_grounded', providing clear alternative and workflow guidance.

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

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

Annotations already convey readOnly=false and idempotent=true. The description adds valuable behavioral details: it returns a subscription ID, requires OAuth, explains per-type behavior, and notes constraints like email/SMS caps and webhook auto-disable. 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 thorough but well-structured, with a clear progression from purpose to requirements to specifics. It is slightly long but each sentence adds necessary information. Could be streamlined slightly, but still effective.

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

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

Given the complexity of 3 parameters (including nested objects and enums) and no output schema, the description covers all needed aspects: type enumeration, parameter constraints, delivery options, prerequisites, and error behaviors. It is comprehensive for an AI agent to invoke correctly.

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

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

Schema coverage is 100%, but the description goes far beyond by explaining each type's required params with concrete examples (e.g., sec_8k items, clinical_trial sponsor/condition requirement) and delivery channel options with constraints. This adds significant meaning.

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

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

The description starts with a clear verb-action ('Create a proactive monitoring subscription') and specifies the resource ('live-data event stream'). It distinguishes itself from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation and proactive monitoring.

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

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

The description explains when to use the tool (to receive alerts for specific event types), specifies prerequisites (Pipeworx OAuth account), and provides details on supported types and delivery channels. It does not explicitly mention when not to use it or compare to alternative tools like 'recent_alerts', but the context is largely clear.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that it returns category-bucketed example questions drawn from the live catalog, which is useful context. 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 trigger phrases first, then explanation, category list, and usage instructions. It is front-loaded with the purpose. It could be slightly trimmed but is efficient for the information provided.

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

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

For a tool with one optional parameter and no output schema, the description is quite complete. It explains the output, usage scenarios, and even provides examples of topics. The annotations cover safety, so no gaps remain.

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

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

Schema coverage is 100% and the description adds value by explaining how to use the topic parameter to focus the spread, providing specific examples like 'finance', 'pharma', 'betting'. This goes beyond the schema's simple list of values.

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

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

The description clearly states the tool returns category-bucketed example questions, each with the exact tool and argument shape. It lists multiple trigger phrases and positions itself as the onboarding entry point. This distinguishes it from siblings like ask_pipeworx, which is a meta-tool for asking questions.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do' and provides instructions for calling with no arguments or passing a topic. It does not explicitly state when not to use it, but the context is clear enough given the sibling list.

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 that the row is deactivated, not deleted, and historical events remain available via recent_alerts. This adds value beyond annotations (readOnlyHint false, destructiveHint false) and does not contradict them.

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

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

Two concise sentences with no wasted words. The key information is front-loaded: the action and ownership constraint.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, ownership constraint, and behavioral effect. The annotations further supplement completeness.

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

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

Schema coverage is 100% with a clear description for the 'id' parameter. The description reinforces that the id comes from subscribe, but does not add new meaning beyond the schema.

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

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

Clearly states 'Cancel a subscription by id.' The verb 'cancel' and resource 'subscription by id' are precise. It distinguishes 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?

Explicitly states ownership enforcement: 'you can only cancel your own subscriptions.' Provides clear context for when to use the tool. No explicit alternatives named, but the constraint is well-defined.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds rich behavioral details: it replaces 4-6 sequential calls, returns a verdict (confirmed/refuted etc.), structured form, actual value with citation, and percent delta. This is substantial context beyond annotations.

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

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

The description is about 120 words, front-loaded with query patterns. It efficiently conveys purpose, domain, returns, and value. While informative, a minor trim could improve conciseness (e.g., 'Replaces 4–6 sequential calls' adds context but is slightly tangential).

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

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

For a single-parameter tool with no output schema, the description covers all necessary aspects: input format, underlying data sources (SEC EDGAR + XBRL), return types (verdict, structured form, value, delta), and rationale (replaces many calls). It is fully self-contained.

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

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

The only parameter 'claim' is fully described in the input schema (100% coverage). The tool description does not add new meaning to the parameter beyond the schema. Baseline 3 is appropriate as the schema already provides examples and format guidance.

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 verifies natural-language factual claims against authoritative sources, specifically company-financial claims via SEC EDGAR + XBRL. Examples like "Is it true that…" demonstrate the verb-resource mapping. Among many siblings, none replicate this verification functionality, providing clear differentiation.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also narrows the domain to company-financial claims (v1). However, it does not mention specific when-not-to-use scenarios or alternative tools, which would make it a 5.

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