Bhagavad Gita

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

Annotations already indicate readonly and idempotent. The description adds context like free default model, BYO key for Anthropic, and return structure (per-model score, confidence, signals). No contradictions.

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

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

Two sentences, no wasted words. Front-loaded with main action and score range, then details. Perfectly 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?

Covers purpose, usage, parameters, and return structure (though no output schema). Provides enough context 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%, so baseline is 3. The description adds meaning by explaining default model, _apiKey necessity, and context disambiguation with examples.

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 probes LLMs for entity knowledge and scores visibility (0-100), with a specific verb and resource. It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on AI visibility scoring.

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

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

Provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains the default model vs. Anthropic key requirement. Lacks explicit when-not-to-use but is still 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 readOnly, openWorld, idempotent, non-destructive hints. Description adds that it routes to 3,641 tools, fills arguments, and returns structured answers with stable citations, which is valuable behavioral context beyond annotations.

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

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

The description is well-structured, starting with a preference note, then listing covered domains, then explaining how it works, and finally giving examples. Every sentence adds value, no fluff.

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

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

For a question-answering tool with no output schema, the description adequately explains that it returns structured answers with citations. Input is fully covered. The tool's behavior is fully characterized 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 description coverage is 100% with all parameters documented as aliases. The description adds example questions but no additional explanation of the aliases. Baseline 3 is appropriate since schema covers it well.

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 using a large set of authoritative sources, and explicitly prefers it over web search. It lists many domains. However, it does not differentiate from the sibling 'ask_pipeworx_grounded'.

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

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

Explicitly states when to use (factual questions about structured data) and gives query trigger phrases. Explicitly prefers over web search. Provides examples.

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. The description adds value by noting the extra LLM call cost and detailing the return structure including refusal reasons, enhancing transparency 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 well-structured with the main purpose upfront, followed by details. Every sentence adds value without redundancy, making it 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?

Despite no output schema, the description fully explains return structure, refusal reasons, and cost tradeoff. For a complex tool with high-stakes usage, this covers all necessary behavioral and contextual details.

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

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

Schema coverage is 100% with all parameters as aliases for 'question'. The description lists all aliases explicitly and explains their usage, adding meaning beyond the schema.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' and explains it extracts answers only from tool results, distinguishing it from ask_pipeworx.

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

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

Explicitly advises using this tool when answers will be quoted or acted upon, and prefers ask_pipeworx for casual lookups, 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral detail: fan-out to multiple data sources, resolver contract with confidence levels, parent event extraction, news fallback handling, safety checks (low-confidence short-circuit, closed market handling), and wide-spread warnings. 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 detailed, covering classifiers, fan-out examples, response shapes, resolver contract, etc. While front-loaded with purpose, it contains extensive information that might be better in documentation. Still, it is well-organized with sections (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.), but conciseness suffers.

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 (3 params, no output schema, many behavioral traits), the description covers all key aspects: input formats, fan-out logic, response structure, edge cases (low confidence, closed markets), safety warnings, and practical usage advice. It is sufficient for correct invocation and interpretation.

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

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

Schema coverage is 100%, but the description enriches each parameter: market can be slug, URL, or question text; depth explains quick vs thorough source counts; include_raw recommends false and specifies when true is needed. Examples in the schema input further clarify usage.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet) and action (research via data pull). It distinguishes from siblings like polymarket_edges (edge detection) and polymarket_arbitrage (arbitrage) by focusing on comprehensive research for a specific bet.

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 use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides extensive examples and context. Although no explicit when-not-to-use is given, the context of sibling tools and safety blocks (low-confidence, closed markets) implicitly guides proper use.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds valuable behavioral context: it fetches latest 10-K financials with proper off-calendar fiscal year handling, pulls FAERS/FDA/trial data for drugs, sorts results by primary metric, and returns citation URIs. 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 dense but efficient, front-loading example triggers and including all necessary information. It covers purpose, usage, behavior, and parameter semantics in a single block. Minor improvement could be structural (e.g., bullet points or line breaks), but it remains concise and informative.

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

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

The description explains inputs (type and values), behavioral specifics (data sources, sorting, fiscal year handling), and output hints (paired data + citation URIs). Without an output schema, the return format is not fully detailed, but the functionality is well-covered. It adequately informs an agent of what to expect.

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

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

Schema coverage is 100%, so the schema already provides descriptions. The description adds context beyond the schema: it clarifies that 'values' should be tickers/CIKs for companies and drug names for drugs, provides examples (e.g., ['AAPL','MSFT']), and explains the effect of the 'type' parameter on data sourcing.

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

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

The description clearly states the tool's function: side-by-side comparison of 2–5 entities (companies or drugs). It immediately gives trigger phrases like 'Compare X and Y' and specifies the data sources (SEC EDGAR for companies, FAERS/FDA/trials for drugs), distinguishing it from siblings like entity_profile (single-entity lookup) and sequential 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 states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing a clear usage directive. It lists the entity types and counts (2–5) but does not explicitly say when not to use (e.g., for single entities), though the sibling entity_profile implies that.

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, idempotent, non-destructive. Description adds details on return value (top-N relevant tools with full schemas, ready to call), consistent with annotations and 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?

Front-loaded with purpose and usage, return info included. Slightly long but each sentence earns its place. Minor improvement possible by splitting into bullet points.

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

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

Despite no output schema, the description fully explains what is returned: names, descriptions, schemas with examples, ready to call. No gaps for this simple search tool.

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

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

Schema coverage is 100%, so description adds minimal extra meaning beyond examples. Baseline 3 is appropriate; no significant enhancement.

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 finds tools by describing data or task, and distinguishes itself from sibling tools which are specific domain tools. It explicitly says to call this FIRST 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?

Provides clear when-to-use guidance: 'Call this FIRST when you have many tools available and want to see the option set.' Implies not for direct answers, effectively differentiating from siblings.

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

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

Annotations already indicate safe idempotent read (readOnlyHint, idempotentHint, destructiveHint false). The description adds value by detailing the data sources (SEC, XBRL, USPTO, etc.), the soft-fail for patents, and the return structure, going 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 long but well-structured with example queries upfront. Each sentence serves a purpose (sources, limitations, return fields), though it could be tightened slightly 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?

Given the complexity of the tool (multiple sources, soft-fails, no output schema), the description adequately sets expectations about what is returned and the current status of patents. It covers major aspects, making it sufficient for an agent.

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

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

Input schema covers both parameters with descriptions (100% coverage). The description reinforces that 'value' accepts ticker or zero-padded CIK, and reiterates the type constraint, adding clarity 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 a comprehensive cross-source profile for US public companies, with specific examples like 'Tell me about X' and lists exact output fields. It distinguishes from sibling tool 'resolve_entity' by specifying that names are not supported.

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

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

Explicitly instructs to 'ALWAYS PREFER over chaining single-pack lookups' for holistic views, and advises using 'resolve_entity' first if only a name is available, providing clear when-to and when-not-to 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 destructiveHint=true and idempotentHint=true, so the description adds minimal behavioral context beyond confirming deletion. No contradictions.

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

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

Two concise sentences, front-loaded with the action and purpose, no unnecessary 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 one-parameter, destructive tool with no output schema, the description adequately conveys purpose, usage, and relationship to siblings.

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 key parameter. The description does not add extra meaning beyond the schema.

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

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

The description clearly states the action (delete) and resource (previously stored memory by key), distinguishing it from siblings like remember and recall by mentioning them.

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 (stale context, task done, clear sensitive data) but lacks explicit when-not-to-use or detailed alternatives beyond pairing 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?

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds context about the process (fetch, extract, emit) which aligns and enriches 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?

Three concise sentences plus a use-case line. Front-loaded with action and purpose, no wasted words. Well-structured for quick understanding.

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?

Describes input, output format, and use cases. No output schema, but explains output as 'single text blob' with markdown format. Missing error handling details but adequate for a simple generation 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% (both parameters described). The description does not add meaningful parameter-specific details beyond the schema, so it meets baseline but does not exceed.

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 'Generate a production-ready llms.txt file' with a specific verb and resource. It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on generation rather than analysis.

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 use cases are given ('getting a client's site indexed... drafting... auditing...'). However, it lacks explicit when-not-to-use guidance or comparison to similar siblings like scan_competitor_ai_presence.

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, so the safety profile is clear. The description adds return field details but no additional behavioral traits 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?

A single, well-structured sentence that front-loads the action and resource, then lists the return. Every word adds value; no wasted space.

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

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

Given the simple parameter set, comprehensive annotations, and the description's explicit listing of returned fields, the description is fully complete for an agent to select 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?

The input schema has 100% coverage with a clear description for the only parameter 'chapter'. The tool description confirms 'by number' but adds no 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?

The description explicitly states the action ('get one chapter'), the resource ('Bhagavad Gita'), and the method ('by number'). It lists the returned fields, making it clear what the tool does. It distinguishes from siblings like 'get_verse' and 'list_chapters'.

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 when to use it (when a specific chapter's details are needed) but does not explicitly state when not to use it or mention alternatives. With siblings available, the context is helpful but not explicit.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds value by detailing the output contents (Sanskrit, transliteration, English translations, commentary), 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?

Two sentences: first states the purpose concisely, second describes the output. No wasted words, front-loaded with the key action and resource.

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

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

For a simple tool with two parameters, full annotations, and no output schema, the description adequately covers purpose, inputs, and output details. It is complete for its complexity level.

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

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

Schema coverage is 100% with clear descriptions for both 'chapter' and 'verse' parameters. The description does not add new meaning beyond the schema, meeting the baseline requirement.

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

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

The description clearly states the verb 'Get', the resource 'single verse (sloka) of the Bhagavad Gita', and specific parameters (chapter and verse number). It distinguishes from sibling tools like 'get_chapter' and 'list_chapters' by specifying the scope as a single verse.

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 context for retrieving a single verse, but does not explicitly state when not to use it or compare with alternatives like 'get_chapter'. However, the context is clear enough for an agent to infer appropriate use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by specifying the return content (chapter number, names, summary, verse count), going beyond the schema.

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

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

Single sentence that efficiently conveys the tool's purpose and output. 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 zero-parameter, simple list tool, the description is complete. It describes the returned data sufficiently despite lacking an output schema.

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

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

No parameters exist (schema coverage 100%), so the description need not explain parameter semantics. The baseline of 4 is appropriate.

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

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

Description explicitly states it lists all 18 chapters of the Bhagavad Gita, with specific return fields (chapter number, Sanskrit name, transliteration, English meaning, summary, verse count). This clearly distinguishes it from sibling tools, which are unrelated.

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 when-not or alternatives, but the tool has no parameters and is a simple retrieval. Given the sibling tools are unrelated, the usage context is clear without further guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds context about return fields and an optional parameter, but does not go 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 concise with two sentences. The first sentence states the purpose, and the second provides usage guidance. No superfluous information.

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

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

Given the tool's simplicity (no required params, one optional boolean, no output schema), the description is complete. It lists the return fields and provides usage context, which is sufficient 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 description coverage is 100% (the only parameter 'include_inactive' has a description in the schema). The description does not add any extra meaning beyond the schema's parameter description, so the baseline score of 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions,' specifying the verb 'list', resource 'subscriptions', and scope 'caller's active'. It effectively distinguishes the tool from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

The description provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use the tool, though it does not mention alternatives or 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?

The description discloses rate limits (5 per identifier per day) and states the feedback is free and does not count against quota. This adds significant value beyond annotations, which only indicate non-readonly, non-idempotent, non-destructive behavior. No contradictions with annotations.

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

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

The description is a single, well-structured paragraph with five sentences. Each sentence serves a distinct purpose: stating purpose, providing usage scenarios, giving content guidance, explaining team response, and noting rate limits and cost. 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 simplicity (2 required params, nested object, no output schema), the description provides all necessary information: when to use, how to structure feedback, rate limits, and cost. 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 description coverage is 100%, so the schema already documents all parameters with descriptions. The description adds minimal extra detail (e.g., guidance to describe issues in terms of tools/packs), but this is largely redundant with the schema's own parameter descriptions.

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

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

The description states a specific verb ('Tell') and resource ('Pipeworx team') and clearly distinguishes the tool's purpose from siblings by detailing the types of feedback (bug, feature, data_gap, praise). It also explicitly differentiates from other tools by noting it does not count against tool-call quota.

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

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

The description provides explicit when-to-use scenarios: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also advises against pasting the end-user's prompt, giving clear behavioral 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?

Adds valuable context beyond annotations: source (CF analytics-engine), no PII, caching duration (5min-1h). Annotations already indicate read-only, idempotent, non-destructive.

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, then use cases, then metadata. 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 single optional parameter, no output schema, and rich annotations, the description is complete: covers output, caching, data source, and privacy.

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 enum descriptions. The description adds nuance about short vs. long windows (hot right now vs. steady-state demand), enhancing the schema's bare enumeration.

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 top tools, top packs, and total call volume over a recent window, distinguishing it from sibling tools like 'ask_pipeworx' or 'discover_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 lists three concrete use cases (discovering hot data, confirming canonical tool, aligning use case) but does not provide when-not-to-use guidance or 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 the tool safe (readOnlyHint, idempotentHint, etc.). The description adds substantial behavioral context: monotonicity checks, partition-sum calculations, Jaccard similarity threshold (≥0.30), placeholder filtering, and the structure of the response. 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: it starts with the critical requirement, then explains each mode with examples and technical details, and finally describes the response. Every sentence adds valuable information; there is no redundancy or filler.

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

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

Given the tool's complexity (two modes, multiple checks), the description is remarkably complete. It covers the required input, the algorithmic checks (monotonicity, partition sum, semantic similarity, placeholder filtering), and the output structure (opportunities array, partition_check object). No output schema exists, but the description compensates adequately.

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

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

Schema coverage is 100%, but the description greatly enriches the parameters by explaining the modes, giving examples of valid slugs and seed questions, and detailing how each mode works internally (e.g., cross-event catches patterns single-event misses). This goes far beyond the schema's brief 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 identifies the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between two modes (event and topic) and contrasts with sibling tools like polymarket_edges and polymarket_kalshi_spread. The verb 'find' and resource 'arbitrage opportunities' are 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 explicitly states the requirement for exactly one of 'event' or 'topic' and warns that calling with no arguments fails. It recommends event mode for specific markets and topic mode for cross-event scanning, providing examples. It also explains the semantic anchor and partition filter to avoid invalid pairs. However, it does not explicitly state when NOT to use the tool (e.g., for simple probability queries).

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 goes far beyond annotations by detailing three model families, edge calculation (including slippage, Kelly fractions, caps), caching at KV level, Fed bets handling, diagnostics for empty segments, and per-sport bias corrections. No contradiction with annotations (readOnly, openWorld, idempotent, non-destructive).

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

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

Description is very lengthy (multiple paragraphs) but well-structured with clear sections and technical details. While every sentence earns its place, overall verbosity may reduce quick comprehension for an AI agent. Could be streamlined without losing essential nuance.

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

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

Given the complexity (9 params, 3 model families, output structure), and no output schema, the description is highly complete: it explains response top-level structure (by_segment, fed_candidates, diagnostics), edge case handling (empty segments, filter skips, Fed note), and knob usage. All required context for correct invocation is present.

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 9 parameters, but the description adds critical context beyond schema: e.g., 'edge is evaluated NET of slippage', 'Kelly is half-Kelly capped at 0.25', 'min_kelly filters single-leg only, partition arbs use min_partition_leg_kelly'. This clarifies parameter interactions and 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?

Description clearly states the tool scans top Polymarket markets to find opportunities where Pipeworx data disagrees with market price, with a specific use case 'what should I bet on today'. It distinguishes from siblings like polymarket_arbitrage and polymarket_kalshi_spread by focusing on edge detection from model disagreements.

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?

Implied usage for discovering opportunities without paging through hundreds of markets, but no explicit when-to-use or when-not-to-use compared to alternative tools. The description does mention tradeable-edge knobs and segment inclusion/exclusion, providing context for filtering.

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

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

The description adds substantial value beyond the annotations (readOnly, openWorld, idempotent, non-destructive) by explaining the two modes, response structure, and crucially the safety fields: compatibility_warning, temporal_alignment, and skipped_cross_type counters. It discloses that spreads may be meaningless when temporal_alignment is false. 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 and front-loaded with the core purpose. Every sentence adds value, covering modes, response, and caveats. However, it is somewhat verbose for a tool description; a slightly more concise version could achieve a 5. Still, it is efficient and informative.

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 (cross-venue comparison, multiple modes, safety fields), the description is comprehensive. It explains what the response contains (leg-by-leg prices, matched spreads, compatibility_warning), handles edge cases (non-equivalent bet shapes, temporal misalignment), and sets expectations about pre-mapped topics. No output schema exists, so the description fully compensates.

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, but the description significantly adds meaning by elaborating on the two modes, providing examples of topic values, and explaining how kalshi_event_ticker and polymarket_event_slug override the topic-mapped sides. It clarifies the interaction between parameters and the behavior of the tool in each mode.

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

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

The description clearly states the tool's purpose as computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies the action (computing spread), resources (two prediction markets), and distinguishes from sibling tools like polymarket_arbitrage which likely focuses on intra-venue 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 explicit guidance on when to use the tool (to compare prices across venues) and when not to (when compatibility_warning fires, indicating non-equivalent bet shapes or unrelated events). It warns that most pre-mapped topics currently return compatibility_warning, setting realistic expectations. No alternative tools are named, but the context is sufficient.

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 scope (scoped to identifier) which adds beyond annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false). No contradiction, and explains dual behavior (single value vs list).

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

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

Three sentences, each earning its place: first states core action, second gives usage and alternatives, third adds scope and pairing. Front-loaded and 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?

For a tool with one optional parameter and no output schema, the description covers all necessary context: input behavior, usage examples, scope, and sibling pairing. 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?

Adds meaning beyond schema by clarifying that omitting the 'key' parameter lists all keys. Schema coverage is 100% with a description, but the usage guidance 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 retrieves a saved value or lists all keys, distinguishing it from siblings 'remember' and 'forget'. The verb 'Retrieve' and specific resource 'value previously saved via remember' are explicit.

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

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

Provides explicit when-to-use context: 'look up context the agent stored earlier' and alternatives: 'Pair with remember to save, forget to delete'. Also explains scope and re-deriving avoidance.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by explaining the behavior of the `mark_read` parameter, the persistence of the feed, and the return structure (source, citation_uri, payload). 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 relatively concise, front-loading the core function. It covers essential points without redundancy, though it could be slightly more structured. It is efficient but not perfectly 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?

The description covers what the tool returns, how to filter, the effect of `mark_read`, polling suitability, and an alternative access method. Given there is no output schema, it adequately explains return values and usage, making it complete for a retrieval 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 descriptions, but the description adds extra meaning, e.g., that `mark_read:true` affects subsequent calls and that `since` expects an ISO timestamp. It provides useful 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 starts with 'Pull fired events from your subscription feed,' clearly stating the verb and resource. It specifies what each returned alert contains, making the tool's function unambiguous. No sibling tool serves the same purpose, so differentiation is not needed.

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 indicates that polling works fine and mentions an alternative HTTP endpoint for scripts/dashboards, providing context for usage. However, it does not explicitly state when not to use the tool or compare it to other tools, missing some guidance on alternatives.

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

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

Beyond annotations (readOnly, idempotent), the description details fan-out to multiple APIs, fallback behavior (GDELT to GNews), USPTO soft-failure, and concurrency, adding 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?

Every sentence is informative: example queries, source details, parameter formats, return structure, and alternative tool. No unnecessary words, well-structured 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?

Despite no output schema, the description explains the return structure (changes[], total_changes, URIs). It covers all parameters, edge cases, and alternative uses, making it complete for this 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 already covers all parameters with descriptions (100% coverage). The description adds practical usage tips (e.g., '30d' for typical monitoring), justifying a score above baseline 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 it provides a change feed for a company in a time window, listing specific sources (SEC, GDELT/GNews, USPTO) and distinguishing from entity_profile, which provides static profiles.

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

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

The description gives explicit example queries and explicitly advises using entity_profile instead for static profiles, 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?

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds context on persistence (24 hours for anonymous, permanent for authenticated) and scoping by identifier, which goes beyond annotations. No contradictions.

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

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

Four sentences, front-loaded with purpose, then usage, then technical details. Every sentence adds value with 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?

Given simple two-parameter schema and no output schema, the description fully explains storage behavior, scoping, persistence, and companion tools. An agent has enough context to use the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description doesn't add significant parameter details beyond what's already in the schema, but it reinforces the purpose with examples.

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

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

The description clearly states the tool saves data for later reuse, with concrete examples (ticker, address, preference) and distinguishes itself from sibling tools like recall and forget.

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

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

Explicitly tells when to use it (discover something worth carrying forward) and mentions alternatives: recall for retrieval, forget for deletion. Also explains scoping and persistence differences for authenticated vs anonymous users.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds that each call cascades through several lookup endpoints internally, replacing 2-3 manual lookups. This provides useful behavioral context.

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

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

The description is concise, front-loaded with purpose, and every sentence adds meaningful information. It uses quotes to illustrate user scenarios and is well-structured without any 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 tool's complexity (two entity types with multiple input forms and outputs), the description fully covers what the tool does, what it returns, and its behavioral characteristics. It compensates for the lack of an output schema.

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

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

Schema coverage is 100%, but the description adds value by explaining what each type returns (e.g., ticker + CIK + citation URI for company, RxCUI + ingredient + brand for drug) and gives example inputs, going beyond the schema's basic descriptions.

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

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

The description clearly states that the tool resolves user-spoken names to canonical identifiers. It provides specific examples and distinguishes itself from sibling tools by advising 'Use FIRST whenever you have a name but need an ID.'

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

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

The description explicitly says to use this tool first when you have a name but need an ID, and gives example queries. However, it does not provide explicit 'when not to use' guidance or mention alternatives among the 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?

Annotations declare read-only, open-world, idempotent, non-destructive. The description adds beyond annotations: it explains that the tool probes each entity with 'ai_visibility_check', ranks results, and returns a ranked list with score, confidence, signal density. This is valuable behavioral context. No contradictions.

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

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

The description is concise at three sentences, each earning its place: first sentence states action and method, second provides a use case, third describes output. No unnecessary 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?

Without an output schema, the description effectively covers what the tool does and returns: a ranked list with score, confidence, signal density per entity. It also explains the input constraints (2-8 entities, first is subject) and optional parameters. This is sufficient for an agent to use the tool correctly.

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

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

Input schema describes all 4 parameters with 100% coverage. The description adds meaning beyond the schema, e.g., explaining that the first entity is treated as the 'subject', that models can be omitted for just workers-ai, and that context disambiguates common names. This surpasses the baseline of 3 for high schema coverage.

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

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

The description clearly states the tool's purpose: comparing AI visibility across multiple entities side-by-side. It uses specific verbs like 'compare', 'probes', 'ranks', 'surfaces', and distinguishes from sibling tools like 'ai_visibility_check' (single entity) and 'compare_entities' (general 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?

The description provides clear context for when to use this tool, e.g., competitive AI-marketing audits. It implies that for single entity checks, use 'ai_visibility_check' instead. However, it does not explicitly state when not to use it or list alternatives, but the usage is well implied.

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

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

Discloses partial failure behavior (bundlephobia slow first measurement, sources_failed list) and aggregation of multiple data sources. Annotations already indicate read-only, idempotent, non-destructive; description adds valuable 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?

Well-structured with purpose, use cases, return fields, and limitations. Slightly verbose but each sentence adds essential information. Could be tightened.

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 all necessary information: what it does, when to use, what it returns, ecosystem limitation, and failure behavior. Without output schema, description provides enough detail for an agent to understand.

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

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

Schema already covers both parameters with descriptions. The tool description doesn't add new parameter information beyond that. With 100% schema coverage, 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 defines as a composite check for npm package safety, popularity, and size. Distinguishes from siblings by mentioning deps.dev and bundlephobia integration and npm-only scope.

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

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

Explicitly states when to use (agent asks about safety/popularity/size of npm packages) and when not to use (other ecosystems, directs to deps.dev:version). Provides 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?

Goes well beyond annotations (readOnlyHint, etc.) by disclosing technical details: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char 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?

Well-structured: starts with core purpose, then usage motivation, pairing, and technical details. Each sentence adds value, though slightly verbose for the technical specifics.

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 input constraints, output format (passages with offsets and scores), algorithm, and pairing advice. Sufficient for an agent to select and 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 description adds meaningful context: 'text you already pulled' clarifies source, 'natural-language query' reinforces query semantics, and explains that limit returns passages with offsets and scores.

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' with specific verb and resource. Distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and contrasting with fetching via the gateway.

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 the record is too big to cram into the prompt') and suggests pairing with another tool. While it doesn't list all alternatives, it provides 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.

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

The description adds behavioral context beyond what annotations provide: it specifies that the tool requires OAuth authentication, details the returned value (subscription id), and outlines constraints on delivery channels (SMS cap, phone verification). Annotations already indicate the tool is not read-only, is idempotent, open-world, and not destructive, but the description enriches these with practical usage 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?

The description is front-loaded with the core action and quickly moves to essential details. It is well-structured with clear sections for types and delivery channels. A minor inefficiency exists (repetition of phone verification steps), but overall it is concise and easy to parse.

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

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

Given the complexity (3 parameters including nested objects, enum, no output schema), the description covers prerequisites, type-specific examples, delivery options, and constraints. The only notable gap is the omission of the 'patent_grant' type from the description, which is present in the schema but not explained. Otherwise, it provides sufficient context for an agent to correctly 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 description provides examples for most subscription types (sec_8k, polymarket_edge, fred_series) but omits the 'patent_grant' type that appears in the schema enum. The schema already contains descriptive comments for each parameter, so the description adds value through examples but is incomplete by missing one type. Overall, it adds moderate additional 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 explicitly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses a specific verb (create) and resource (subscription), and clearly distinguishes from sibling tools like unsubscribe, list_subscriptions, and recent_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?

The description provides clear context for when to use the tool: it requires a Pipeworx OAuth account (anonymous/BYO cannot persist), details supported subscription types with examples, and explains delivery channels and constraints such as SMS cap and phone verification. However, it does not explicitly enumerate when not to use this tool versus alternatives, which would elevate the score to 5.

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

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

Description adds significant context beyond annotations: ownership enforcement, deactivation behavior, and side effects on historical events. Aligns with annotations (destructiveHint=false, idempotentHint=true) without contradiction.

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

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

Two concise sentences front-loading the action. Every sentence adds value with no wasted words.

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

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

For a simple tool with one parameter and clear annotations, the description covers all essential aspects: purpose, constraints, outcome. No output schema needed since return is not described but behavior is explained.

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

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

Schema already covers id parameter with 100% description coverage. Description doesn't add additional information about the parameter, but no further clarification needed due to simplicity. Baseline score of 3 is appropriate.

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

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

Clearly states the action (cancel) and resource (subscription). Title clarifies it's for alerts, but description doesn't explicitly mention alerts, slightly reducing specificity. 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 constraint (only cancel own subscriptions) and explains behavioral outcome (deactivation vs deletion, retention of history via recent_alerts). Provides clear when-to-use context and references a related sibling.

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 as safe. Description adds valuable behavioral context: it returns verdicts (confirmed, refuted, etc.), with actual value and percent delta, and specifies data sources and domain limitations.

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

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

Description is front-loaded with trigger phrases and well-structured. It is slightly verbose but every sentence earns its place by providing critical context about behavior, domain, and return values.

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

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

Given no output schema, the description fully explains return values (verdict, structured form, actual value, citation, delta). It also states limitations (only company-financial claims) and data sources. Combined with full schema coverage and rich annotations, it is completely adequate for an agent to use correctly.

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

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

Schema describes the single parameter with examples. Description reinforces the parameter with additional examples and domain context. Schema coverage is 100%, so baseline is 3; description adds value by clarifying what types of claims are accepted.

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

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

Description starts with explicit trigger phrases and states it is for fact-checking claims, specifically company-financial claims via SEC EDGAR + XBRL. It clearly distinguishes from siblings, as no other tool does the same.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and mentions it replaces multiple sequential calls. However, no explicit when-not or alternatives are provided, though none are needed given sibling uniqueness.

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