Giantbomb

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that it returns per-model {score, confidence, signals, raw_response} and a combined view, plus the condition for Anthropic probing. This adds 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 concise (4 sentences) and front-loaded with the core action. Each sentence adds value—purpose, default behavior, optional feature, use cases—without redundancy.

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

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

Given the tool has 4 parameters (1 required) and no output schema, the description adequately explains the return structure and the optional Anthropic integration. It does not address rate limits or errors, but annotations (openWorldHint) partially compensate.

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 meaning by explaining the default model, the purpose of '_apiKey' (BYO key, pass-through to Anthropic), and the role of 'context' (disambiguation). This extra context elevates the score above the baseline of 3.

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

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

The description clearly states it probes LLMs for knowledge about a business/brand/product/topic and scores visibility per model. It uses specific verbs ('probe', 'score') and distinguishes from sibling tools like 'ask_pipeworx' or 'deep_research' by focusing on AI visibility 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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to provide '_apiKey' for Anthropic probing. However, it does not explicitly mention when not to use this tool or suggest alternatives, which limits 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 mark it read-only/idempotent/non-destructive; the description adds behavioral context by explaining routing behavior, citation URIs, broad coverage, and that it works on every tier in one fast call. It does not disclose potential failure modes or rate limits, but those are less critical given the read-only, open-world annotation profile.

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 front-loaded with a clear 'PREFER OVER WEB SEARCH' directive, then examples, then escalation guidance. It is longer than average but every sentence adds usage context; it remains readable with clear topic groups.

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 breadth and lack of an output schema, the description fully covers when to use it, what it does, what it returns (structured answer with citation URIs), and when to escalate to siblings. It also includes concrete examples to anchor selection and invocation.

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

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

The schema already describes the single question parameter and all five aliases with 100% coverage, so the description does not need to add param details. The examples illustrate acceptable queries but do not add meaning beyond the schema's 'natural language request' 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 identifies a specific verb+resource: it routes factual questions to 5,529 tools across 1,455 verified sources and returns structured answers with citations. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

It gives explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'Use whenever the user asks...', 'START HERE for most questions') and names alternatives ('Step up only when needed: ... ask_pipeworx_grounded ... deep_research'). It also covers exclusions by saying when not to step up, e.g., for broad/multi-part questions.

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 valuable context: it is experimental, candidate routing is enabled only when under test, no candidate is currently active so it matches ask_pipeworx, and it is a full working router rather than a stub. 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 four sentences long, each serving a distinct purpose: beta status, current operational state, usage instruction, and reassurance that it is fully functional. It is front-loaded with the most important information and does not waste words, though slightly longer than necessary.

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

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

No output schema is provided, but the description states 'same response shape' and explicitly references ask_pipeworx as the stable counterpart, allowing the agent to infer output format from that sibling. It also explains the experimental nature, fallback behavior, and current equivalence to the stable router. This is reasonably complete given the pointer to the stable tool.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for 'question'. The description only says 'same arguments' without adding syntax or format details beyond what the schema already provides. Since the schema fully covers parameter semantics, 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 it is a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes from the stable ask_pipeworx sibling by highlighting the experimental routing improvements and its current beta status.

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

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

Explicit guidance is given: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that results are compared against the stable router and mentions the current no-active-candidate state, implying when to use the stable alternative. However, it does not explicitly list exclusions 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?

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the full output structure including {answer, evidence, confidence, source, fetched_at, refusal_reason}, the exact refusal reasons, and the fact that it costs one extra LLM call. It also explains the grounding constraint ('using ONLY what the tool result contains'), adding significant behavioral context not captured by 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, then flows into mechanism, output format, use cases, and cost tradeoff. Every sentence provides necessary information without redundancy, earning a top score for efficiency and organization.

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 provided, the description thoroughly explains return values and failure modes, making the tool's behavior predictable. It also covers when to use it, cost implications, and the grounding guarantee. This is complete for an agent to select and invoke the tool correctly without further documentation.

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

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

Schema coverage is 100% and the schema already documents the single required parameter 'question' plus five aliases. The description adds no additional parameter-specific guidance, which is acceptable given the schema's completeness, so the baseline of 3 applies.

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

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

The description clearly states this is a 'hallucination-resistant answer mode for high-stakes reads' and explains the mechanism: it routes to the right tool, fetches data, then extracts an answer using only the tool result. It differentiates from the sibling ask_pipeworx by emphasizing grounding and explicit refusal behavior, making the purpose unmistakable.

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

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

The description explicitly says to use 'whenever an answer will be quoted, cited, or acted on' and gives examples of high-stakes uses (financial verdicts, legal claims, medical lookups). It also states when not to use it: 'prefer ask_pipeworx for casual lookups,' providing a direct alternative and a cost-based tradeoff.

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 far beyond the annotations (readOnly, openWorld, idempotent, not destructive) by detailing the entire workflow: market resolution, classification, parallel fan-out, evidence packet return, and safety mechanisms like low-confidence short-circuits and closed-market handling. It also discloses resolution-rule risk and edge cases, providing rich behavioral context that prevents misuse.

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 verbose (multiple paragraphs with dense detail) given the tool's complexity. It is front-loaded with the primary purpose and usage, then naturally flows into response shapes and edge cases. While every sentence adds value, the length could be trimmed without losing clarity. An appropriate size for the complexity, but not concise.

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

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

Given the tool's complexity (classifiers, fan-outs, response shapes, resolver contract, parent events, news fields, safety checks, resolution rules) and the absence of an output schema, the description thoroughly covers all aspects. It explains return values, edge cases, and blocking conditions, ensuring the agent can use the tool correctly and interpret results without additional guidance.

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% description coverage for all three parameters (market, depth, include_raw). The description adds examples for market input (slug, URL, question text) and explains the 'depth' quick vs thorough behavior, but this mostly echoes the schema descriptions. With high schema coverage, the description's marginal contribution is limited, meeting the baseline expectation.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and mechanism (pull Pipeworx data). However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edges, missing an opportunity to guide selection among related Polymarket 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 provides explicit usage examples: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear context for when to invoke the tool. However, it lacks explicit 'when-not-to-use' guidance or direct comparison to sibling tools, leaving some ambiguity for agents choosing among Polymarket-focused tools.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds nothing beyond 'Single character.', offering no behavioral insights like what data is returned or any 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?

Extremely short (2 words) but this is under-specification rather than conciseness. The description is not front-loaded with useful information.

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

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

Despite having an output schema and one required parameter, the description provides no context about return values or how the tool fits among 40+ siblings. It is completely inadequate for understanding the tool's role.

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 0% and the description fails to explain the required parameter 'guid_or_id'. It does not add meaning beyond the schema, which is just a string type.

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 'Single character.' is a tautology that merely restates the name 'character' without specifying any action (e.g., get, retrieve) or distinguishing from siblings like 'games' or 'companies'.

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 guidance on when to use this tool versus alternatives such as 'entity_profile' or 'search'. The description provides no context for selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, etc. The description adds the critical behavioral trait 'API offline as of 2026-05' and specifies return fields, which goes beyond the annotations.

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

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

The description is two sentences long, contains no fluff, and immediately conveys the core functionality and a critical note.

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 presence of an output schema and only 3 optional parameters, the description sufficiently covers purpose and the offline note, though it lacks detail on filter syntax which could impair agent usage.

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

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

With schema_description_coverage at 0%, the description must compensate for parameter meaning, but it only vaguely mentions 'API filter expression' and does not explain how to construct the filter string or what the limit/offset parameters control.

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 or filter video game companies in Giant Bomb by API filter expression' with a specific verb and resource, and it distinguishes the tool from siblings by naming the data source and filter capability.

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

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

The description provides clear context for using the tool (listing/filtering companies) and notes the API is offline, but does not offer when-not-to-use guidance or mention alternatives among 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?

The description explains data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs) and that results are sorted by primary metric. Annotations already indicate read-only and idempotent behavior; the description adds useful context without contradicting 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 but somewhat lengthy. It starts with trigger phrases for quick recognition, then explains data sources and behavior. Every sentence adds value, though minor redundancy could be trimmed for conciseness.

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

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

Given no output schema, the description explains return format ('paired data + pipeworx:// citation URIs per entity') and that results are sorted. It covers the tool's value proposition and data coverage for both entity types. Lacks details on error handling or edge cases, but sufficient for correct invocation.

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

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

Schema coverage is 100%. The description adds meaning beyond the schema by detailing what data each 'type' returns (e.g., 'type=company pulls LATEST 10-K revenue + net income + cash + long-term debt') and that 'values' are tickers or drug names with constraints (2–5 items).

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 performs 'side-by-side comparison of 2–5 companies or drugs' and provides trigger phrases like 'compare X and Y'. It clearly distinguishes from sequential lookups by emphasizing it replaces '8–15 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 includes 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving explicit preference guidance. It also lists specific query patterns (e.g., 'which is bigger') that signal when the tool should be invoked.

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 richly discloses behaviors beyond annotations: decomposition into facets, parallel routing to 5,529 tools, explicit gaps[] for unanswered facets, never inventing answers, citation URIs with fetchability guarantee, hop field, contradictions[] for standard/thorough, semantic excerpting, account/paid plan requirements, and latency expectations. This goes far beyond the read-only/idempotent 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 wall of text and repeats key points (e.g., ask_pipeworx alternative, gaps[] behavior) multiple times. While all information is relevant, it could be trimmed for decisiveness. It front-loads the critical sign-in requirement, but overall it is verbose for a tool description.

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 covers return values: findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, hop field, gaps[], and contradictions[]. It also covers latency, account tiers, and failure modes. For a complex tool, this is complete and self-sufficient.

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 critical semantics: it defines depth values in behavioral detail (quick=3 facets, standard adds gap recovery + contradictions, thorough adds lead-chasing and is paid), and clarifies that the question parameter supports broad/multi-part natural language. This exceeds the baseline of 3 by providing practical implications of each parameter.

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

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

The description clearly states the tool performs 'grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, and distinguishes it from siblings by explicitly contrasting with ask_pipeworx for single lookups and current-news topics. It also clarifies it is 'NOT open-web search', removing ambiguity.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data'. It also gives alternatives and exclusions: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx', plus a fallback if not signed in. This is exemplary usage direction.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by stating that each result includes curated examples and is ready to call directly without further schema lookup. 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 front-loaded with purpose and domains, includes examples, and every sentence adds value. Slightly long but justifiably detailed for a discovery tool.

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

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

Without an output schema, the description thoroughly explains what is returned (names, descriptions, schemas with examples) and the scope of domains. Provides enough context for an agent to understand its value.

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 context about aliases for query (task, q, description, search) and limit default/max, which goes beyond the schema definitions.

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

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

Description clearly states it finds tools by describing data or task, lists many domains, and explains it returns top-N relevant tools with full schemas ready to call. This distinguishes it from sibling tools like search or specific data 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 says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies when not needed.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant context: it fans out across multiple sources in one parallel call, lists exact fields returned (CIK, recent filings, fundamentals, etc.), and discloses the patents API sunset with soft-fail behavior. No contradiction.

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

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

The description is longer than ideal but front-loaded with example queries. Every sentence adds value—covering purpose, sources, returned fields, limitations, and alternatives. Could be slightly tighter, but efficient for the tool's complexity.

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

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

Despite no output schema, the description comprehensively explains what the tool returns: CIK, filings, fundamentals, patents (with caveat), news, LEI. It also specifies parallelism and data sources. No gaps remain for an agent to understand the tool's full behavior.

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

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

Schema coverage is 100% and the description reiterates and clarifies parameter meanings: type is only 'company' for now, value must be ticker or zero-padded CIK (not name). It adds context about using resolve_entity for names, which the schema does not provide.

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

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

The description uses specific verbs ('profile', 'fans out across') and resource ('US public company') with clear example queries. It distinguishes from sibling tools like resolve_entity and deep_research by stating 'ALWAYS PREFER over chaining single-pack lookups' and explicitly noting when to use resolve_entity 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 provides explicit when-to-use guidance ('ALWAYS PREFER... when the user asks for a holistic view'), when-not-to-use ('names not supported – use resolve_entity first'), and even mentions a fallback behavior for patents ('soft-fails until reactivated'). Alternatives are clearly named.

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 destructiveHint=true and idempotentHint=true. The description confirms the destructive nature but does not add further behavioral details (e.g., permanence, effects on related data). It adds modest value 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 two sentences, front-loaded with the core purpose, and contains no extraneous information. Every sentence adds value.

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

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

For a simple delete tool with one parameter and no output schema, the description is complete. It covers the action, when to use, and relates to sibling tools, satisfying all contextual needs.

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 fully documents the single parameter 'key' with description 'Memory key to delete'. The description does not add additional semantics beyond the schema, resulting in 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 action 'Delete a previously stored memory by key.' It specifies the verb (delete) and resource (stored memory), and distinguishes from siblings 'remember' and 'recall' by being the delete operation.

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 context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also pairs with 'remember' and 'recall', providing alternatives and context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint; description adds no new 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?

Extremely concise single sentence, front-loaded, no wasted words, though slightly underspecified.

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?

Minimal description for a simple tool; output schema exists but not described; lacks usage context.

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

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

With 0% schema description coverage, the description adds 'guid or id' but doesn't clarify format or distinguish between guid and id; example helps slightly.

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 'Single game by guid or id' clearly states the verb (retrieve) and resource (game) and distinguishes from sibling 'games' tool.

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

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

No when-to-use or alternatives guidance; just states what it does without context for when to prefer this over other tools like 'games'.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds the critical note that the API is offline as of 2026-05, which is key behavior. Otherwise, no additional traits disclosed.

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 action. No fluff. The offline note is important but placed at the end; could be more prominent.

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?

Tool has 4 parameters with 0% schema description coverage; description only partially covers two. Existence of output schema reduces need to describe returns, but missing parameter docs and the offline note are critical 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 0%. Description mentions 'API filter expression' and 'sort field' but does not describe limit, offset, or provide format details for filter/sort. Examples in input schema help but are not part of 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?

Description clearly states it lists/filters Giant Bomb games with optional parameters, and specifies returned fields. Distinguishes from sibling tools like 'game' (singular) and 'platforms' (different resource).

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 guidance on when to use this tool versus alternatives like 'game' or 'search'. The description does not mention prerequisites or exclusions, only optional parameters.

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. The description adds valuable behavioral context: it fetches the page, extracts title/description/key links, and emits standard markdown format. This explains the process and output nature 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 three sentences long, front-loaded with purpose, followed by process and use cases. Every sentence adds value; there is no redundancy or verbosity.

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 parameters (2, one required), no output schema, and annotations covering safety, the description provides complete context: what it does, how it works, output format, and use cases. Nothing essential is missing for an AI agent to select and invoke this 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% (both 'url' and 'max_links' are described in the input schema). The tool description does not add additional parameter meaning beyond what the schema provides. 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 uses a specific verb ('Generate'), identifies the resource ('llms.txt file for any URL'), and clearly states the end result. It distinguishes itself from sibling tools like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on generating the standard llms.txt file for AI crawlers.

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

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

The description lists three explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), providing clear context for when to use the tool. It does not specify when not to use or name alternatives, but the use cases are sufficient for 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. The description adds that it returns specific fields and defaults to active subscriptions (unless include_inactive is set), which provides some 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 extremely concise, consisting of two sentences that convey all necessary information without any fluff or 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 simplicity (one optional parameter, no output schema), the description is complete. It explains the purpose, returned fields, and typical use cases, leaving no significant 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%, and the description does not add additional meaning beyond what the schema provides for the one optional parameter. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields (id, type, params, created_at, last_fired_at, fire_count). It distinguishes from siblings like subscribe and unsubscribe, which perform different actions.

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 usage 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 invoke the tool, though it does not explicitly list 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 are all false and offer little safety guidance, so the description carries full responsibility. It discloses key behaviors: filing without an account returns a claim_token, the token can be used later to read resolution status, rate-limiting (5/day), free usage, and that feedback does not count against tool-call quota. It also explains the digest/roadmap impact. This is rich behavioral context well beyond the annotations, with no contradiction.

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

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

The description is longer than the calibration 'high' example, but every sentence contributes unique information: purpose, usage triggers, exclusion, claim_token mechanics, rate limits, cost, and road map impact. Content is front-loaded with the main verb and enumerates categories before detail. Slightly dense, but no filler, so a 4 rather than 5.

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 feedback tool with no output schema, the description covers all needed context: what happens when you file (claim_token returned), how to retrieve status later, constraints (rate limit, quota), and what to include in the message. The sibling list shows this is distinct from query/assistant tools. The description fully prepares an agent to use the tool effectively and know when to redirect to other servers.

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 documents all parameters well. The description adds valuable semantics beyond that: it explains the claim_token parameter's special usage ("pass the pwfb_… token that filing returned, with no other arguments") and advises on message specificity. It also clarifies the optional context object is structured with pack/tool/vertical. This elevates the parameter understanding beyond the bare schema.

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

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

The description opens with a clear, specific purpose: "Tell the Pipeworx team something is broken, missing, or needs to exist." It enumerates the types of feedback (bug, feature, data_gap, praise) and explicitly distinguishes this tool from siblings like ask_pipeworx or discover_tools by framing it as a report/feedback channel, not a query tool.

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

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

Provides explicit when-to-use guidance: "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 gives a clear exclusion: "ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead." This goes beyond typical descriptions and directly tells the agent when not to use the tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds valuable context: derived from CF analytics-engine, no PII, cached 5min-1h. No contradictions.

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

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

Purpose is front-loaded, followed by bulleted use cases and a concise note on data source and caching. Every sentence serves a purpose; 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 covers what it does, what it returns, data provenance, caching, and use cases. It fully equips an agent to decide when and how to invoke it.

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

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

Schema coverage is 100% with a description for each enum value. The description adds meaning by explaining that shorter windows surface hot trends while longer show steady-state demand, enriching the schema.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a recent window. It distinguishes from siblings like discover_tools and search by focusing on trending usage by AI agents.

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

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

Explicitly lists three use cases (discovering hot sources, confirming canonical tools, aligning use cases) and mentions caching behavior. Lacks explicit when-not-to-use or alternative tool names, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description 'List/filter' is consistent and adds no new behavioral context, but 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 a single sentence, very concise. However, it could be slightly more informative without losing conciseness. It earns points for being short and to the point.

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

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

Given the tool has three parameters and no schema descriptions, the description is insufficient. It does not explain pagination, filtering syntax, default behavior, or expected output, despite an output schema existing.

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 0%, and the description only says 'List/filter' without explaining the parameters 'limit', 'filter', or 'offset'. No details on allowed values, formats, or semantics beyond parameter names.

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 'List/filter' and the resource 'platforms', which is distinct from sibling tools like 'companies' or 'games'. However, it lacks specificity about what kind of platforms, though context likely resolves ambiguity.

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 guidance on when to use this tool versus alternatives. The description does not provide any context for selection, prerequisites, or exclusion criteria.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint all appropriate. The description adds rich behavioral context: fill check against live CLOB depth, partition filter, semantic anchor for cross-event pairs, placeholder filtering, and response structure. 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 lengthy but well-structured: a concise summary first, then detailed breakdowns for each mode, internal filters, response format, and fill check. Every sentence adds value; minor redundancy could be trimmed without losing clarity.

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

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

Given the tool's complexity (two modes, multiple internal checks, no output schema), the description is remarkably complete. It explains the response shape (opportunities[] with gap_pp, suggested_trade, reasoning), the partition_check subfield, and the fill check with realizable edge. It even points to polymarket_fill_risk for custom sizing.

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 enhances understanding by explaining the meaning and behavior of each parameter: event slugs vs seed questions, the internal processing (walking child markets, date-axis checks, partition checks), and cross-event Jaccard similarity filtering.

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 arbitrage opportunities via monotonicity violations and partition-sum checks. It explicitly distinguishes between three usage modes: no-args trending scan, single-event mode, and cross-event topic mode, with concrete examples and differentiation from 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?

Provides explicit guidance on when to use each argument: no args for trending scan, 'event' for a specific Polymarket market slug, 'topic' for cross-event scanning. It also warns about conditions that make a signal untradeable (realizable_edge_pp ≤ 0) and notes the fill check for real-time depth confirmation.

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

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

The description provides extensive detail on model families, response segments, edge calculation, filters, caching, and diagnostics. It adds significant context beyond the annotations (readOnlyHint, etc.), with 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 lengthy and dense, containing detailed technical explanations. While well-structured, it could be more concise for quick agent parsing.

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

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

Given the tool's complexity (9 params, no output schema), the description thoroughly covers response structure, edge calculations, filters, and diagnostics, fully compensating for missing output schema.

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

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

Schema coverage is 100% with descriptions for all 9 parameters. The description adds extra context, such as explaining slippage_pp with fee information and min_partition_leg_kelly in relation to min_kelly.

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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It distinguishes itself from sibling tools by focusing on edge discovery, not arbitrage or tracking.

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 it is 'built for what should I bet on today' and describes knobs for filtering. However, it does not explicitly compare to sibling tools or state 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 indicate read-only, idempotent, non-destructive behavior. The description adds extensive behavioral detail: response structure (tracked, expired, snapshot_dates), trend classification, decay computation, and limits (60-day TTL, daily closes). 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 longer but well-organized into purpose, argument details, response format, and limits. It uses clear formatting with newlines. Could be slightly more concise, but the structure aids readability.

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

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

The description is thorough, covering all aspects an agent needs: input parameters, full response structure with fields, and important limitations (TTL, decay computation). No output schema exists, so the description compensates well.

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 reinforces parameter meaning (days and window) and adds context for default values and allowed window families not explicitly listed in the schema. Since schema coverage is 100%, the description adds some value but is not essential.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry. It answers a specific question and distinguishes itself from siblings (like raw polymarket_edges snapshots) by focusing on historical 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?

The description gives a concrete example of when to use (comparing a fresh wide edge vs. a 3-week-old wide edge), but does not explicitly state when to use alternative tools or when not to use this one. The context is clear enough for correct 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the tool is clearly a safe read operation. The description adds behavioral context about partial fills converting arb to unhedged directional position (the dominant loss mode), which is valuable 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 well-structured with clear headings and front-loaded purpose. While verbose, every sentence adds value (mode explanations, output details, risk warnings). Some redundancy could be trimmed, but it remains organized 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?

Despite no output schema, the description comprehensively lists all return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and per-leg details. It also explains risks (partial fills, thin legs, forced directional risk), making the tool fully self-contained for an AI agent.

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

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

Schema description coverage is 100%, so parameters are already documented. The description adds semantic meaning by explaining default values (e.g., size_usd default 1000), interpretation differences for buys vs sells, and basket mode's settlement notional interpretation. This goes 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 checks realizable vs theoretical edge against CLOB order book depth, distinguishes between single-market and basket modes, and specifies when to use it (before arbitrage signals or trades above $500). This differentiates it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns against relying on theoretical overround on thin books, providing clear when-to-use and when-not-to-use context.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description expands significantly with details on compatibility checks (matched_pairs, skipped_cross_type), temporal alignment, and leg-pair comparison logic. 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 with valuable information but somewhat long. It front-loads the core concept and uses clear sections. Could be slightly more concise without losing critical details.

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

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

Given the tool's complexity, no output schema, and annotations that provide minimal behavioral guidance, the description fully compensates. It covers response structure, safety fields, compatibility warnings, and edge cases (no matching outcomes, temporal alignment).

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 three parameters. The description adds context: topic parameter lists 10 pre-mapped shortcuts, explicit parameters override the topic, and the interaction between parameters is explained. This goes beyond basic schema descriptions.

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

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

The description clearly defines the tool as computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It uses specific verbs and resources (cross-venue spread, leg-by-leg prices) and distinguishes from sibling tools (no other spread tool exists).

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 two usage modes (topic shortcuts and explicit tickers) and provides detailed guidance on when spreads are meaningful via compatibility_warning fields. It also warns that most pre-mapped topics return warnings, setting proper expectations.

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 and idempotentHint=true; description adds scoping details (anonymous IP, BYO key hash, account ID) and pairing context, going beyond annotations without contradiction.

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

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

Two sentences with no redundancy; purpose and usage are front-loaded. Every sentence adds value.

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

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

For a simple read-only tool with one optional parameter and no output schema, description covers functionality, scoping, and relationship to sibling tools 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?

With 100% schema coverage, the description adds meaning by explaining that omitting the key lists all keys, which is not stated in 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 value saved via remember or lists all keys when key is omitted. It distinguishes from siblings remember and forget by specifying the retrieval role.

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 implies when not (avoid re-deriving). It mentions pairing with remember and forget but does not explicitly list alternative tools for similar tasks.

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

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

Annotations indicate readOnly=true and idempotent=true, but description adds that setting mark_read:true flags events as read, mutating state. This is a behavioral disclosure beyond annotations. Also describes return fields.

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. Efficient but could be slightly more structured (e.g., bullet lists). 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?

Covers key aspects: what returns, filtering, mark_read effect, polling suitability, alternative access. No output schema but description of return fields suffices. Complete for a read 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 description adds usage examples for type (e.g., 'sec_8k') and clarifies since format (ISO timestamp). Enriches parameter understanding beyond schema.

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

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

Clearly states it pulls fired events from subscription feed. Specific verb 'pull' and resource 'fired events'. No explicit differentiation from siblings like 'list_subscriptions', but context implies this is for alerts feed specifically.

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?

Mentions polling works fine and provides alternative GET endpoint for scripts/dashboards, guiding when to use tool vs API. Does not explicitly say when not to use, but provides context.

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

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

Beyond annotations that declare read-only, open-world, and idempotent behavior, the description adds rich behavioral details: fan-out to multiple sources, fallback logic (GDELT→GNews), USPTO soft-fail, and return structure with citation URIs.

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 but slightly verbose with multiple example queries in the opening; a more streamlined opening could improve conciseness 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?

With no output schema, the description fully explains the return structure (changes[], total_changes, citation URIs) and covers all parameter usage, sources, and fallback behavior, leaving no gaps for the agent.

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

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

Although schema coverage is 100%, the description adds significant value by explaining 'since' format with examples (ISO date and relative shorthand), recommending typical values, and clarifying that 'value' accepts ticker or CIK.

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

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

The description clearly states the tool provides a change feed for a company over a time window, lists example queries, and distinguishes from sibling 'entity_profile' by specifying it returns dynamic changes vs static profile.

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

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

The description gives explicit when-to-use guidance with example queries and directly names the alternative 'entity_profile' for static profile needs, leaving no ambiguity about which tool to choose.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the agent knows this is a safe, idempotent read operation. The description adds no extra behavioral details (e.g., pagination behavior, default limits, or data freshness). With annotations covering safety, a score of 3 is appropriate.

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

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

The description is extremely concise (two words), but at the cost of essential detail. It does not front-load critical information like parameter usage or result format. A good description should be brief yet informative, but this is under-specified.

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

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

Given the tool has three optional parameters with no schema descriptions and an output schema (not described), the description should explain filtering, pagination, and output structure. It fails to provide sufficient context for an AI agent to use the tool effectively without additional assumptions.

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 0%, meaning no parameter descriptions in the schema. The description does not explain what 'filter' expects (e.g., format like 'platform:94' from the schema example) or how 'limit' and 'offset' control pagination. Parameter names are somewhat self-explanatory, but the lack of explicit semantics leaves room for misinterpretation.

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 'List/filter releases' clearly identifies the action (list/filter) and resource (releases). It is specific enough to distinguish from unrelated siblings, but does not specify the type of releases (e.g., software releases, product releases), missing an opportunity for full clarity.

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 no guidance on when to use 'releases' versus alternative tools like 'search', 'companies', or 'platforms'. With many siblings, the absence of usage context makes it hard for an AI agent to select the correct tool.

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

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

Annotations indicate idempotent and non-destructive. Description adds critical behavioral context: key-value scope by identifier, retention policy (persistent for authenticated, 24h for anonymous). 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, each essential: purpose, when to use, storage details, pairing with other tools. No fluff, front-loaded with purpose. Highly 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, behavior, and relationships. No output schema, but could mention return value for completeness. Still very complete for a simple write tool.

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

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

Schema description coverage is 100% with clear parameter descriptions and examples. Description does not add extra parameter info, but schema already fully explains key and value. 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 saves data for reuse across conversations or sessions, using specific verb 'save' and resource 'data'. It distinguishes itself from siblings 'recall' and 'forget' by mentioning pairing.

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

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

Provides explicit usage scenarios like 'when you discover something worth carrying forward' with examples (ticker, address, preference). Does not explicitly mention when not to use or alternatives beyond recalled siblings, but context is clear 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?

Annotations already cover read-only, open-world, idempotent, and non-destructive nature. The description adds substantial behavioral context: graceful degradation when GLEIF/OpenFIGI is unavailable, explicit labeling of unresolved identifiers under 'unresolved', source attribution for every identifier, and the fact that it cascades through multiple lookup endpoints. This goes well beyond the structured annotations and gives the agent a clear model of edge cases.

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 example queries and a clear purpose statement. The 'SUPPORTED TYPES' section is structured and information-dense. Every sentence contributes something useful: source details, handling of unresolved IDs, degradation behavior, and efficiency gains. It is not bloated; it is a model of efficient, well-organized tool documentation.

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

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

Despite lacking an output schema, the description explains what identifiers the tool returns (CIK, ticker, LEI, FIGI, RxCUI, etc.), how unresolved items are handled, and that it replaces 2-3 manual lookups. It covers complexity (multiple sources, cascades, degradation) comprehensively. For a tool with this level of complexity, the description is unusually complete.

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

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

The input schema already describes both parameters with 100% coverage, so the baseline is 3. The description adds meaningful enrichment by explaining what 'type' supports (company/drug) and giving concrete examples for 'value' (ticker, CIK, name, brand/generic). It also clarifies what identifiers are returned for each type, which helps the agent choose appropriate inputs. This is valuable, though the schema already covers the basic semantics.

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

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

The description has a specific verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers'. It clearly distinguishes itself from sibling tools by stating 'Use FIRST whenever you have a name but need an ID' and by detailing the identifier types (CIK, LEI, FIGI, RxCUI). This is a crisp, unambiguous 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?

The description gives an explicit usage directive: 'Use FIRST whenever you have a name but need an ID.' It also provides concrete example queries that should trigger the tool. However, it does not name specific alternatives or state when not to use it, so while the primary context is clear, the exclusionary guidance is implicit rather than 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, idempotentHint, and non-destructive behavior. The description adds behavioral details: it probes each entity with ai_visibility_check, ranks by score, and returns score, confidence, and signal density per entity. No contradiction.

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

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

The description is a single paragraph packed with information, including an example. While effective, it could be slightly restructured for scanning ease. No wasted words.

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

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

Given no output schema, the description explains the return format (ranked list with score, confidence, signal density). It covers purpose, usage, parameters, and behavior, making the tool self-contained and easy to invoke.

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 meaning: entities first treated as subject, rest as competitors; models lists supported values; _apiKey clarifies conditionality; context explains disambiguation. This enhances understanding beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. This distinguishes it from sibling tools like ai_visibility_check (single probe) and compare_entities.

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

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

The description provides a clear use case (competitive AI-marketing audits) and an example question. It implicitly distinguishes from ai_visibility_check but does not explicitly state when not to use it or mention all alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant value by detailing the composite nature (fans out across deps.dev and bundlephobia), partial failure behavior, and timing for bundlephobia first measurement (5-30s). No contradiction with annotations.

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

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

The description is relatively long but every sentence adds value. It front-loads the core purpose and then provides details on return format, ecosystem scope, and failure handling. Could be slightly more concise, but 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?

Despite no output schema, the description thoroughly explains the return format (summary block, per-advisory details, links, alternative versions) and partial failure handling. With 2 well-documented parameters and comprehensive behavioral info, it is fully adequate for agent use.

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 parameters. The description adds minor value by noting scoped packages are accepted and that version defaults to latest, which is already implied by the schema description but reinforced.

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 license, advisories, version history, and bundle size. It distinguishes itself from siblings by explicitly noting NPM ecosystem focus and alternative approaches for other ecosystems.

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 provides when to use the tool (e.g., 'is X safe/popular/small' or 'what does adding lodash cost me') and notes NPM-only limitation in v1, directing users to deps.dev for other ecosystems. Partial failures are also explained.

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

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

Annotations already declare readOnly, openWorld, idempotent, and not destructive. The description adds the specific return fields (name, resource_type, deck) and the offline status, providing useful behavioral context beyond annotations.

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

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

Two sentences plus a note: front-loaded with core functionality, no wasted words. The offline notice is appropriately placed at the end.

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

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

The description covers the main function and return fields, but lacks pagination details for 'page' and 'limit' parameters. Given the offline note, completeness is adequate but not thorough.

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 low (25%), but the description explains the 'resources' parameter by listing allowed types and hinting at comma-separated format. However, it does not describe 'page' or 'limit' parameters. Partial compensation.

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

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

The description clearly states it searches across multiple Giant Bomb resource types and specifies the return fields. However, it does not explicitly distinguish from sibling tools like 'search_within' or specific entity tools, so a 4 is appropriate.

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 usage-critical note that the API is offline as of 2026-05, telling agents not to use it. But it offers no guidance on when to prefer this tool over alternatives (e.g., specific entity 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?

Description adds rich behavioral details beyond annotations: embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K) with truncation flag, and return structure (offsets, similarity scores). Annotations already declare readOnly/OpenWorld/idempotent, and description fully aligns.

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 3-4 sentence description with front-loaded purpose. Every sentence adds essential information (usage, pairing, technical details). No redundant or filler content.

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 clearly states what is returned ('top-N passages with character offsets and similarity scores'). It also covers edge cases (truncation, pairing) and provides sufficient context for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100% with descriptions for all three parameters. Description adds value by specifying max length for 'text' (~200K chars), default for 'limit' (5), and concrete query examples, enhancing schema information.

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

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

The description clearly states the tool performs 'semantic search INSIDE a fetched record,' specifying exact use cases (SEC 10-K, article, long tool result). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and contrasting with general search.

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

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

Description explicitly says 'Use when the record is too big to cram into the prompt,' providing clear context. It also mentions pairing with ask_pipeworx_grounded. No direct exclusions, but implied for non-text or small records.

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 key behaviors: requires OAuth, returns subscription ID, includes delivery channel details (always-on feed, email, SMS with cap, webhook with signing secret). Annotations don't contradict; description adds valuable context beyond readOnlyHint and idempotentHint.

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

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

Description is fairly long but front-loaded with main purpose. Every sentence contributes value; could be slightly more condensed but not wasteful.

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

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

Covers all aspects: types, parameters, delivery options, prerequisites, limitations. Even without output schema, it states the return value (new subscription ID). 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 has 100% coverage, but description adds significant meaning with type-specific examples, validation rules (phone verification, webhook HTTPS-only), and clarification of required fields (e.g., sponsor or condition for clinical_trial).

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 'Create a proactive monitoring subscription to a live-data event stream.' It includes the verb 'create' and resource 'subscription', and distinguishes from sibling tools like list_subscriptions 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?

Describes when to use (e.g., for SEC filings, polymarket edges) and prerequisites like Pipeworx OAuth account and phone verification. Mentions limitations (10 SMS/day). Could more explicitly state when not to use, but context is clear.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description goes beyond annotations by detailing the output (category-bucketed example questions with tool+argument shapes) and the fact that it draws from a live catalog. 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 longer but well-structured, starting with alternative phrasings, then explaining the output and usage. Every sentence adds value. Could be slightly trimmed, but it effectively communicates the tool's role without redundancy.

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

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

Given the tool's role as an onboarding aid with no output schema, the description fully covers what the tool returns, how to call it, and its place among sibling tools. It even mentions learning how to call meta-tools, which is critical for new users. 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 one parameter 'topic' described as 'Optional focus area: finance | pharma | ...' The description adds examples of accepted values ('finance', 'pharma', 'betting') and explains the effect of omitting the parameter (full spread), which provides context beyond the schema.

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

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

The description clearly states the tool's purpose as an onboarding entry point for new users to learn what questions Pipeworx can answer. It uses specific verbs ('returns category-bucketed example questions') and explicitly distinguishes from siblings by positioning itself as the first tool to use when unfamiliar with the system.

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 guidance on when to use this tool: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also provides usage variants: no arguments for full spread or 'topic' argument to focus. It lacks a clear statement of when not to use it, but the context implies it is for exploration.

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 details beyond annotations: row is deactivated (not deleted) and historical events remain available. Annotations only indicate idempotent and non-destructive, so description provides crucial 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?

Two sentences, concise and front-loaded with the action. No unnecessary words, every sentence adds value.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, ownership constraint, and data lifecycle effects 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 has 100% coverage including the parameter description. The description repeats 'by id' and 'subscription id' but adds no new semantic 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 'Cancel a subscription by id', providing a specific verb and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description includes ownership enforcement ('you can only cancel your own subscriptions'), giving clear context for when to use. It lacks explicit alternatives 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?

Annotations declare read-only, open-world, and idempotent traits, but the description goes far beyond by explaining exact verdict types, the meaning of could_not_verify vs unsupported, the verification_error field, and the routing logic. This is substantial behavioral context not available in annotations alone.

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 information-dense, with each sentence contributing valuable details (triggers, routing, verdicts, error semantics, efficiency). It's well-organized and front-loaded with purpose and usage, though some redundancy could be trimmed 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?

For a complex tool with multiple pipelines, verdict types, and error handling, the description is remarkably complete. It explains return values in the absence of an output schema, covers edge cases (could_not_verify, unsupported), and provides sufficient context for safe invocation.

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

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

Schema coverage is 100% with descriptions for both claim and tolerance_pct. The description adds extra meaning for tolerance_pct: overrides implied tolerance, recommended 1-2 for hallucination detection, and default cap of 5. It also gives concrete examples for the claim parameter, enhancing clarity.

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: natural-language claim verification against authoritative sources. It provides multiple trigger phrases and distinguishes itself from siblings by noting it replaces 4-6 sequential calls, making it the dedicated fact-checking tool rather than a general search or research tool.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates between company-financial claims (SEC EDGAR fast path) and any other claim (grounded pipeline), and warns that could_not_verify should not be treated as evidence, providing clear when-not-to-use semantics.

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