Twitch

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

Annotations already declare readOnly, idempotent, and non-destructive traits. The description adds valuable context: default model is free, Anthropic requires a user-provided key with direct payment, and the key is passed through without hidden costs. It also explains the return structure (per-model 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?

The description is well-structured with the main purpose front-loaded. It uses four sentences covering purpose, default behavior, key handling, return format, and use cases. There is minimal redundancy, though it could be slightly tighter.

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

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

No output schema exists, so the description compensates by detailing return fields (score, confidence, signals, raw_response) and a combined view. It also addresses cost, authentication, and optional disambiguation, making it sufficiently complete for an agent to use the tool correctly.

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

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

Schema coverage is 100%, but the description enriches parameters beyond the schema: it explains why models array has 'anthropic' option, the _apiKey parameter's cost implications, and the context parameter's disambiguation role. This adds significant meaning for an AI agent.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100). It distinguishes itself from sibling tools like ask_pipeworx or entity_profile by focusing on AI visibility scoring, and it mentions specific use cases (AI-marketing audits, pre-launch brand checks).

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 use cases but lacks explicit when-to-use vs. when-not-to-use guidance or direct comparison to alternatives like deep_research or entity_profile. The implied usage is clear, but no exclusions or alternative tool references are provided.

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 and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context: it routes the question to the appropriate tool, fills arguments, returns stable pipeworx:// citation URIs, works on every tier, and makes one fast call. No contradiction with annotations, and it does mention that it handles breaking news via live news feeds.

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

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

The description is front-loaded with the core directive 'PREFER OVER WEB SEARCH', then systematically covers domains, routing behavior, trigger phrases, examples, and alternative tools. Although it is long, every sentence earns its place—no fluff, and the structure flows from directive to specifics to escalation path.

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 no output schema, the description compensates by explaining the return format ('structured answer with stable pipeworx:// citation URIs'). It covers the tool's broad scope, usage context, alternatives, and even performance characteristics. This is a complete guide for an AI agent to select and invoke the tool correctly.

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

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

The schema already covers 100% of parameters with aliases and a description for 'question', so the baseline is 3. However, the description adds significant semantic depth by enumerating what kinds of questions are valid (current data, real-world entities, numbers), offering examples, and instructing on phrasing ('what is', 'find', 'get the latest'). This goes beyond the schema's generic 'Your question or request in natural language'.

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 routes questions to one of 5,529 tools across 1,455 verified sources and returns structured answers with citations. It lists concrete data domains (SEC filings, FDA drug data, etc.) and explicitly contrasts itself with siblings like ask_pipeworx_grounded and deep_research, making its unique role 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?

It explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', and provides clear 'step up only when needed' guidance for ask_pipeworx_grounded and deep_research. It also gives trigger phrases like 'what is' and 'look up' plus concrete examples, leaving no doubt about when to use this tool.

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

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

Annotations already mark it as read-only and idempotent. The description adds substantial context beyond that: it clarifies the experimental status, that candidate routing improvements may be active, that it currently matches ask_pipeworx exactly, and that it falls back to nothing (i.e., it is a full working router). This is rich behavioral disclosure beyond the annotation safety 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 a single, densely informative paragraph. While it is longer than strictly necessary, every sentence adds value (experimental nature, current status, usage guidance, no-fallback clarification). It is well-structured and front-loaded with the main purpose.

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

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

For a tool with no output schema, the description covers all critical aspects: what it does, how it relates to stable versions, when to use it, its experimental behavior, and that it is fully functional. The mention of 'same response shape' indirectly covers return expectations. This is complete for the tool's complexity.

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

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

Schema description coverage is 100%, and each parameter (including all aliases) is fully described in the schema. The description does not add any parameter-specific semantics, so the baseline score 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 beta version of ask_pipeworx, a universal router with the same tools and response shape. It distinguishes itself from the stable ask_pipeworx by highlighting its experimental nature and candidate routing improvements. The verb 'use' is implied, and the resource is explicitly defined.

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 explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and contrasts it with the stable router, implying when not to use it. This gives clear guidance on when to prefer this beta tool over its stable counterpart.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses specific refusal reasons ('not_in_source', 'no_tool_match', etc.), states that answering uses 'ONLY what the tool result contains,' and explains the cost of an extra LLM call. This is rich behavioral context not present in 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 dense yet well-organized: it opens with the core value proposition, then explains routing and extraction, gives the exact return contract, and ends with usage guidance and cost tradeoffs. Every sentence adds meaningful information 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?

With no output schema provided, the description supplies a complete return contract including success and refusal shapes, the meaning of each refusal reason, and the extra cost tradeoff. It also covers when to choose this tool over siblings, making the context fully sufficient for invocation.

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

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

The input schema has 100% coverage with detailed alias descriptions for the question parameter. The description does not add parameter-specific semantics beyond what the schema already provides, so the 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 identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes it from sibling ask_pipeworx by emphasizing evidence extraction and refusal behavior. It explicitly states the return shape and the types of questions it handles, making the purpose unambiguous.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and even lists example domains (financial verdicts, legal claims, medical lookups). It also names the alternative ask_pipeworx and advises preferring it for casual lookups, plus mentions the extra LLM call cost.

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. The description goes far beyond: details fan-out logic, classifier list, response shapes, resolver contract, parent_event extractor, news fallback fields, safety short-circuits, illiquid spread handling, and resolution-rule risk. No contradictions with annotations.

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

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

The description is very long but well-organized with clear sections, examples, and field definitions. Every sentence adds unique information, but it could be slightly more streamlined without losing essential details. It is functional rather than 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?

No output schema is provided, so the description must describe response shapes. It thoroughly explains result.market, result.analysis, result.evidence, resolver contract, parent_event, news fields, and safety behaviors. Covers edge cases like closed markets, wide spreads, and cancellation rules. Extremely complete.

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

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

Schema coverage is 100%, baseline 3. The description adds substantial meaning: explains 'market' can be slug/URL/question text, 'depth' controls evidence sourcing (quick vs thorough), and 'include_raw' controls payload size with explicit use cases. Examples further clarify parameter usage.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It details inputs (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison), and implicitly distinguishes from sibling tools like 'polymarket_arbitrage' by focusing on single-bet research.

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

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

Provides explicit use cases ('Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'), fan-out examples per category, and guidance on inspecting market_match_confidence before trusting analysis. Also describes blocking conditions (low confidence, closed markets) and when to check cancellation rules.

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

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

Adds significant behavioral context beyond annotations: describes data sourced (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return format (paired data + citation URIs). No contradiction with readOnlyHint, idempotentHint, etc.

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

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

Description is well-structured with usage triggers at the start, functional details in the middle, and efficiency claims at the end. Some redundancy (e.g., mentions parallel call and replaces sequential lookups twice) but overall each 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 tool with 2 parameters, no output schema, and rich annotations, the description covers input semantics, data sources, sorting, and return format. Could mention limitations (e.g., only public companies, only FDA drugs) but is otherwise 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 100%, and the description enriches parameters by explaining that 'type=company' pulls revenue/net income/cash/debt and 'type=drug' pulls FAERS counts, approval counts, trial counts. Also clarifies the 'values' array expects tickers/CIKs for companies and names for drugs.

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 performs side-by-side comparisons of 2-5 companies or drugs, using specific verb 'compare' and resource 'entities'. It distinguishes from sibling tools like 'entity_profile' and 'validate_claim' by emphasizing parallel lookups vs sequential, and specifies data sources (SEC EDGAR for companies, FAERS for drugs).

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

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

Explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', and provides natural language examples for invocation (e.g., 'X vs Y', 'rank these companies'). Implicitly guides against using when a single entity lookup suffides (use entity_profile instead).

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, openWorldHint=true, idempotentHint=true, destructiveHint=false, but the description adds rich behavioral context: account requirements, paid tier for thorough, parallel decomposition, returns findings with citations and gaps[], never invents data, semantically excerpts large records, latency expectations, and a second-hop iteration behavior. Contradicts no annotations; the openWorldHint aligns with the 'not open-web search' clarification and gap[] disclosure.

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 appropriately sized for a complex tool with many behavioral caveats. It front-loads the account requirement and key distinctions early, then systematically covers usage, depth options, output format, and limitations. Every sentence adds information, though it is long and some details (e.g., Pipeworx URL) could be moved to schema or external docs, but it remains structured and not padded.

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

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

Given the tool's complexity (2 params, rich annotations, no output schema), the description is remarkably complete. It explains what the tool returns (findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[]), how depth levels behave, latency, account requirements, and when NOT to use it. The absence of an output schema raises the burden, and the description fully compensates.

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

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

Schema coverage is 100% with detailed descriptions for both parameters (question and depth enum with meanings), so baseline is 3. The description adds extra value by explaining depth levels in more operational terms (gap recovery, contradictions scan, paid plan for thorough, latency expectations), which goes beyond the schema and helps with parameter choice.

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 tool performs grounded multi-source research across Pipeworx's 1455 structured data sources, decomposing questions and routing to 5,529 tools in parallel. It distinguishes itself from siblings by explicitly contrasting with ask_pipeworx (single lookup) and noting it is NOT open-web search, making its purpose and scope unambiguous.

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

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

Provides explicit when-to-use guidance: best for broad/multi-part questions over structured data, and explicitly says to use ask_pipeworx for single lookups or breaking/current-news topics. It also gives alternative tool names (ask_pipeworx) and context on depth tiers, covering both usage and exclusions comprehensively.

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. The description adds that results include full input schemas with curated examples and are ready to call directly, which goes beyond annotations. No contradictions.

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

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

The description is front-loaded with the key purpose, followed by domain list and behavior details. Slightly long but each sentence earns its place. Could be trimmed slightly but no major waste.

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

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

Given the simple parameter structure (6 params, 5 aliases) and no output schema, the description covers purpose, usage, result contents (top-N tools with schemas), and when to call. Lacks mention of pagination or error handling, but not critical for this tool.

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

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

Schema coverage is 100%, with all parameters described. The description adds value by clarifying that 'query' accepts aliases (task, q, etc.) and provides natural language examples, improving usability beyond the schema alone.

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

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

The description starts with a specific verb+resource ('Find tools by describing the data or task') and provides a comprehensive list of domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools. It explicitly states the primary use case: call first to discover options.

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 when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools'. Lacks explicit instructions on when not to use (e.g., when the needed tool is already known), 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 indicate readOnly, openWorld, idempotent. Description adds details: fans out across multiple sources, specifies returned fields, notes patents API sunset and 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?

Description is detailed and informative, but somewhat lengthy. Every sentence adds value, front-loads with examples. Slightly verbose but still effective.

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

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

No output schema, but description fully explains return values (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and covers limitations and fallbacks. Complete for a profile 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% but description adds context: explains that type only supports 'company', value can be ticker or CIK, explicitly excludes names and suggests resolve_entity. Adds meaning beyond schema.

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

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

Clearly states it creates a 'full cross-source profile of a US public company' with examples like 'Tell me about X' and 'company profile for Microsoft'. Distinguishes from siblings by advising to prefer this over chaining single-source lookups and mentioning resolve_entity for names.

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 to use for holistic view, 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups'. Gives when-not-to-use: names unsupported, direct to use resolve_entity first. Provides clear input examples.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds value by explaining the purpose of deletion (clearing sensitive data, stale context) and reinforcing that it is a deletion operation. No contradictions with annotations.

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

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

The description is very concise: two sentences that front-load the action and follow with usage context. Every word earns its place with no redundancy.

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

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

For a simple 1-parameter delete operation, the description covers all essential aspects: what it does, when to use, and related tools. No output schema is needed as the behavior is straightforward.

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

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

The input schema covers 100% of parameters and provides a description for 'key'. The tool description mentions 'by key' but adds no new semantic detail beyond what the schema already 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 ('Delete') and resource ('memory by key'), making the purpose immediately clear. It also distinguishes itself from sibling tools 'remember' and 'recall' by explicitly mentioning them as related but different operations.

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

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

The description explicitly states when to use the tool: when context is stale, task is done, or to clear sensitive data. It also provides guidance by directing to pair with remember and recall, covering usage context thoroughly.

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. The description adds process details (fetch page, extract title/links) but no behavioral traits beyond what annotations imply.

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: first states core action, second describes process, third lists use cases. Concise, front-loaded, no redundant 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?

With 2 simple parameters, clear annotations, no output schema needed (output described as text blob), and explicit use cases, the description is fully adequate for agent 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% so the schema documents both parameters fully. The description adds no extra meaning beyond the schema descriptions; it only restates the URL parameter's purpose.

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

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

The description states the specific verb 'Generate' and resource 'llms.txt file', and distinguishes it from 38 sibling tools by focusing on a unique purpose of creating an AI crawler index file.

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?

Lists three explicit use cases (client site indexing, own project, competitor auditing) but does not specify when not to use or name alternatives; however, no sibling tool overlaps in functionality.

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

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

Annotations already indicate read-only, idempotent nature. Description adds that it returns specific fields (streamer name, title, viewer count, thumbnail) and that game name is auto-resolved to ID, providing useful behavioral detail 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 an example. Every part adds value with no redundancy. Highly efficient and front-loaded with the core action.

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

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

Covers main purpose, filtering, and output fields. Lacks pagination details beyond the 'first' parameter, but given annotations and schema, it is sufficient for an agent to use correctly.

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

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

Schema coverage is 100%, so description's added value for individual parameters is limited. The example and note about omitting game provide some contextual meaning, but do not significantly enhance what the schema already conveys.

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 gets live Twitch streams with optional game and language filters. Purpose is specific and actionable, but does not explicitly differentiate from sibling tools like top_games or search_channels.

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 context: omit game for overall top streams, and includes an example. However, it does not specify when to use this tool over alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds value by listing the exact profile fields returned (id, display name, view count, etc.) and showing the expected input structure with an example. This helps the agent understand what to expect beyond the annotations, though it does not discuss rate limits or authentication details already implied by the _apiKey parameter.

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 plus a useful example. It is front-loaded with the purpose, immediately tells what the tool does, and the example shows concrete usage. Every sentence is necessary and there is 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 lookup tool with high schema coverage and no output schema, the description covers the key inputs and outputs. It lists the return fields and provides an example. Minor missing details: error handling if user not found, or clarification that the lookup is by exact login only. Overall, sufficient for an agent to use the tool correctly in most scenarios.

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

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

Input schema coverage is 100% with descriptions for both login and _apiKey. The description's mention of 'login (username)' and the example adds minor context but does not provide significant new semantics beyond what is already in the schema per-property descriptions. With full coverage, the baseline is 3.

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

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

The description clearly states the tool looks up a Twitch user by login (username) and lists the profile fields returned. This distinguishes it from sibling tools like search_channels which likely do fuzzy searches. The verb 'Look up' and the resource 'Twitch user/channel' are specific, and the example reinforces the exact match intent.

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 does not explicitly state when to use this tool versus alternatives like search_channels or entity_profile. It implies exact lookup by login, but provides no guidance on when to choose different tools or what preconditions exist (e.g., must have known username). This is adequate but lacks proactive 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 safe read-only behavior. Description adds context on returned fields but does not mention any additional traits like pagination or rate limits. Since annotations cover safety, a minor gap is acceptable.

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

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

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

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

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

No output schema exists, but description enumerates return fields. Tool is simple (one optional param), so description fully covers needed context.

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

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

Schema coverage is 100% with clear description for the single optional parameter. Description does not repeat parameter info, which is acceptable as baseline 3.

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

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

Description clearly states 'List the caller's active subscriptions' and specifies returned fields (id, type, params, etc.). Distinguishes from sibling tools like subscribe/unsubscribe.

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

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

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Implies when not to use (modification tasks) by mentioning alternative actions.

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, so the description must carry the full transparency burden. It does so by disclosing rate limits (5/day), the claim_token round-trip behavior, that it's free and doesn't count against quota, and that the team reads digests daily. No contradiction with annotations.

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

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

The description is appropriately sized for its complexity; it front-loads the purpose and then efficiently covers exclusions, token behavior, rate limits, and quota impact without repetition. Every sentence contributes unique operational guidance.

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 no output schema, the description fully explains what feedback filing returns (claim_token) and how to retrieve status/fixes later. It also covers scope constraints (Pipeworx-only tools), rate limiting, and prompt hygiene, making it complete for an agent to handle the tool correctly.

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

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

Input schema already has 100% coverage with descriptions for all four parameters, so baseline is 3. The description adds practical semantics: mapping type enum values to concrete situations, clarifying the claim_token usage pattern ('pass it back later as...'), and instructing that message should not include end-user prompts.

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

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

The description clearly states that the tool sends feedback to the Pipeworx team about broken, missing, or desired functionality. It enumerates specific categories (bug, feature/data_gap, praise), distinguishing it from sibling ask_* tools which are for querying, not submitting feedback.

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 conditions (bug, feature/data_gap, praise) and an explicit exclusion for tools from other MCP servers. It also tells users what to include (Pipeworx tool/pack names) and what not to include (end-user prompts), plus how to follow up using a claim_token.

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=false. The description adds valuable context: data derived from CF analytics engine, no PII, cached 5min-1h depending on window. No contradictions.

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

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

The description is concise with no filler. It uses bullet points for use cases and a clear sentence structure. Every sentence adds value.

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

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

Given the tool's simplicity (one optional parameter, read-only, no output schema), the description covers purpose, behavioral details (caching, data source), and use cases comprehensively.

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

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

The schema has 100% coverage for the single parameter (window). The description adds meaning beyond the enum values by explaining the trade-offs between shorter and longer windows, guiding selection.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over recent windows. It distinguishes itself from siblings (e.g., discover_tools) by focusing on trending data derived from other agents' usage.

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 specific use cases (discovering hot data sources, confirming canonical tool choice, checking alignment) and explains window trade-offs. It does not explicitly mention when not to use, but the use cases provide clear guidance.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, which the description does not contradict. The description adds rich behavioral context: walking child markets, checking monotonicity, partition_sum computation, Jaccard threshold, placeholders filter, and fill check against live CLOB depth. No annotation contradiction.

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

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

The description is lengthy (over 300 words) and could be more concise. However, it is well-structured with clear sections and front-loaded with the core purpose and modes. Some details about fill check and Jaccard similarity could be condensed without losing meaning.

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

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

Despite no output schema, the description specifies the response structure: opportunities[] with gap_pp, suggested_trade, reasoning, and partition_check fields in event mode. It covers edge cases (placeholders, low similarity, fill check) and gives complete guidance for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, with both parameters described. The description adds meaning beyond schema by explaining the difference between `event` mode (single event slug) and `topic` mode (cross-event scanning with seed question), including examples and behavioral details like Jaccard similarity and partition filter.

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

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

The description starts with a clear verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (no args, event, topic) and provides specific guidance, effectively differentiating from sibling tools like polymarket_edges and 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?

Explicit guidance is given: call with NO args for trending scan; pass `event` for a specific market (recommended); pass `topic` for cross-event scanning. It also tells when not to use it (e.g., for custom sizing use polymarket_fill_risk), providing clear when-to and when-not-to instructions.

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, idempotentHint, and non-destructive behavior. The description adds substantial behavioral context: caching behavior ('Cached 1h at the KV level'), explanation of model families, edge calculation, slippage handling, and diagnostics. No contradictions with annotations.

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

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

The description is quite lengthy (multiple paragraphs) but well-structured with sections, bullet points, and clear details. While it provides comprehensive information, it could be more concise without sacrificing clarity.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, diagnostics) and includes details on edge_pp_net, kelly_fraction, and tradeable-edge knobs. It is complete for a tool with 9 parameters.

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 baseline is 3. The description adds meaningful context beyond the schema, such as explanations for slippage_pp (execution slippage) and min_partition_leg_kelly (differentiating from min_kelly). It also clarifies defaults and behavior for several parameters.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific use case 'what should I bet on today.' It is specific about the resource and action, though it does not explicitly differentiate from sibling tools like polymarket_arbitrage, but the context makes its unique purpose apparent.

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

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

The description provides clear context for when to use this tool ('discover opportunities without paging hundreds of markets') and includes knobs for filtering. However, it does not explicitly state when not to use it or mention alternatives among siblings.

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

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

Description adds extensive behavioral details beyond annotations, including data structure, trend computation, handling of expired opportunities, and limitations like snapshot TTL and caching gaps. No contradictions with annotations.

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

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

Description is well-structured with clear sections for purpose, parameters, response format, and limitations. It is front-loaded with the core purpose and uses no wasted sentences.

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 the absence of an output schema, the description fully documents the response structure and computed fields, leaving no ambiguity about what the tool returns.

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

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

Description supplements schema with default values, clamping behavior, and explanation of window parameter options, adding meaningful usage guidance beyond the schema's type and 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 the tool provides edge persistence and decay telemetry from daily snapshots, and distinguishes itself from the sibling 'polymarket_edges' by focusing on time series and trend 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?

Description provides context for when to use (e.g., to answer how long an edge has existed and if it is shrinking), but does not explicitly exclude alternatives or mention when not to use.

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

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

The description discloses detailed behavioral traits beyond annotations: ladder walking, return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), basket-mode per-leg details, warning about partial fills converting arb to directional position. No contradiction with annotations (readOnly, idempotent).

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

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

The description is well-structured with clear sections for single-market and basket modes, front-loaded purpose. Every sentence adds necessary detail for the tool's complexity; no wasted words.

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

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

Given the tool's complexity (two modes, 4 parameters, no output schema), the description fully covers parameter usage, behavioral details, return fields, and risk warnings. Annotations cover safety and idempotency. 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 coverage is 100%, so baseline is 3. Description adds meaning by explaining mode context (single-market vs basket) and size_usd interpretation (max spend vs target proceeds, settlement notional). Provides usage defaults and constraints beyond schema descriptions.

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

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

The description clearly states the tool checks realizable versus theoretical edge against live order book depth, and distinguishes two modes (single-market and basket). It explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use it.

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

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

The description provides explicit when-to-use guidance: before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. It explains why (theoretical overround not capturable on thin books, partial fills create directional risk).

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description goes beyond by explaining safety fields (compatibility_warning, temporal_alignment, skipped_cross counters) and their meaning when results are unreliable. 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 detailed but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds information, though it could be slightly more concise. Front-loads core purpose effectively.

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

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

No output schema exists, so the description must explain the response. It does so thoroughly: leg prices, matched spread array, top_spreads_pp, and safety fields with conditions. This fully prepares the agent to interpret results.

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

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

Schema coverage is 100% with descriptions. The description adds value by listing all 10 topic shortcuts explicitly and clarifying that explicit parameters override topic-mapped ones. This extras help in correct parameter usage.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket, distinguishing it from sibling tools like polymarket_arbitrage. It specifies the verb ('spread') and the resource ('cross-venue prices'). The purpose is unambiguous.

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

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

The description explicitly outlines two modes (topic shortcuts vs explicit tickers) and provides guidance on when each is appropriate. It warns that pre-mapped topics often return compatibility warnings, implying use of explicit mode for specific known events. Although it does not directly contrast with sibling tools, the guidance 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 already declare readOnlyHint, idempotentHint, destructiveHint. Description adds valuable detail on scoping by identifier (anonymous IP, BYO key hash, or account ID) and pairing with siblings, going 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 concise, with three sentences that are front-loaded and each sentence adds distinct value: purpose, usage context, and pairing.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully covers behavior, scope, and relationship to siblings, leaving no ambiguity.

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

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

Schema has 100% coverage with one optional 'key' parameter and description. The description adds the crucial behavior that omitting the key lists all saved keys, which is not explicit 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?

The description clearly states the tool retrieves a previously saved value or lists keys, using specific verbs 'retrieve' and 'list', and distinguishes from siblings 'remember' and 'forget'.

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

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

The description explicitly says to use it for looking up previously stored context without re-deriving it, and pairs it with remember and forget. It lacks explicit 'when not to use' but provides clear 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?

The description discloses the key behavioral trait of optionally marking events as read via mark_read, which is a state change. However, this contradicts the annotation readOnlyHint=true, which implies no state modification. The description adds important context that annotations fail to capture, hence a 4 but with an annotation contradiction flagged.

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

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

The description is four sentences, front-loaded with the core action, and each sentence adds value. No redundancy or filler. Perfectly concise for the information provided.

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

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

Despite lacking an output schema, the description explains return fields (source, citation_uri, raw event payload). It covers all parameters, provides use-case guidance (polling, alternative endpoint), and gives sufficient context for an agent to use the tool correctly. 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 coverage is 100%, baseline 3. The description adds meaning by explaining that type and since are filters, limit controls max events, mark_read flags events as read, and unread_only is implied. It provides use-case context beyond the schema, such as 'Polls work fine' and the alternative endpoint, justifying a 4.

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

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

The description clearly states 'Pull fired events from your subscription feed' and details the returned fields (source, citation_uri, raw event payload). It distinguishes itself from sibling tools by providing a specific verb and resource, though no direct sibling for alerts exists. The description is specific and unambiguous.

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

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

The description provides explicit guidance on when to use the tool: filter by type and/or since ISO timestamp, use mark_read to acknowledge events, and notes that polling works fine. It also mentions an alternative GET endpoint for scripts/dashboards, giving clear usage context and exclusions.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds performance (parallel call), data source fallback details, PatentsView API sunset limitation, and return structure (grouped changes, counts, citation URIs). No contradictions.

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

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

Single paragraph packs purpose, examples, data sources, parameter guidance, and sibling distinction. Front-loaded with example queries. Slightly dense but efficient; no wasted words. Could benefit from bullet points but remains clear.

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

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

High complexity with multiple sources and fallbacks; no output schema. Description covers purpose, usage context, parameter semantics, behavioral traits (parallel, fallback, soft-fail), and return structure. Complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description adds value by providing example values ('7d', '30d', '3m', '1y'), recommended defaults ('Use "30d" or "1m"'), and accepting both ticker and CIK for 'value'. Enhances clarity beyond the schema.

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

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

Description starts with example queries, clearly states it's a 'change feed for a company' in a given window, and lists specific data sources (SEC EDGAR, GDELT→GNews, USPTO). It distinguishes from the sibling tool 'entity_profile' which provides static profiles.

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

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

Provides explicit guidance: use entity_profile for static profiles instead. Includes example query patterns and suggests default 'since' values like '30d'. Also describes fallback behavior (GDELT→GNews) and soft-fail for USPTO, helping the agent decide when to use or avoid.

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

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

The description adds behavioral context beyond annotations: key-value scoping by identifier, persistence for authenticated users, and 24-hour retention for anonymous sessions. This complements the idempotentHint and destructiveHint annotations without contradiction, providing a complete behavioral 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 three sentences with no wasted words. It is front-loaded with the core purpose, followed by usage guidelines and behavioral details. Every sentence earns its place.

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

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

Given the tool's simplicity (two required string params, no output schema), the description covers purpose, usage, storage behavior, lifetime, and sibling tools. It is complete for an agent to select and invoke correctly, even without additional structured information.

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

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

Schema coverage is 100%, so the baseline is 3. The description's examples (e.g., 'subject_property') add minor context but do not significantly enhance understanding beyond the schema descriptions. The value is adequate but not exceptional.

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 ('Save') and resource ('data') and clearly states the purpose ('reuse later across conversations or sessions'). It distinguishes from sibling tools by mentioning 'recall' and 'forget', making it clear what this tool does versus others.

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

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

The description explicitly says 'Use when you discover something worth carrying forward' and provides examples (ticker, address, preference). It also recommends pairing with recall and forget. While it doesn't explicitly state when not to use, the guidance is clear and sufficient for an AI agent.

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

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

The description discloses significant behavioral traits beyond the annotations: identifiers that cannot be resolved are explicitly listed under 'unresolved' rather than omitted, and LEI/FIGI enrichment degrades gracefully if GLEIF or OpenFIGI is unavailable. These details add valuable context about output behavior and error handling.

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 a couple of sentences but well-structured, starting with trigger examples, then the core purpose, followed by detailed supported types and fallback behavior. While every sentence carries relevant information, it could be slightly more succinct; however, it is appropriately sized for the complexity.

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

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

With no output schema provided, the description fairly completely explains the return values for each entity type, including specific identifiers (CIK, LEI, FIGI, RxCUI) and their sources, as well as graceful degradation behavior. It also notes the internal cascading lookups, making it highly informative for an agent.

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

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

Schema coverage is 100% and the schema already provides detailed descriptions for both parameters (type enum and value formats per entity type). The tool description repeats these formats but does not add additional semantic nuance beyond what the schema already conveys. Since schema does the heavy lifting, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: to resolve a user-spoken name to canonical/official identifiers, with a specific verb and resource. It provides numerous examples of trigger phrases and distinguishes itself from sibling tools like entity_profile by focusing on ID resolution rather than profiles.

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

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

The description explicitly instructs to 'Use FIRST whenever you have a name but need an ID,' providing clear context for when to use the tool. It also lists supported entity types and input formats. However, it does not mention when not to use it or name any alternative tools explicitly.

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, etc. Description adds that it probes each entity with ai_visibility_check and returns ranked list with score, confidence, signal density. Also explains models parameter auth requirements, adding 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?

Three sentences, front-loaded with main purpose. No wasted words. Each sentence serves a purpose: what it does, how it works, and when to use.

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 context, parameter roles, and return type (ranked list). Given no output schema and good annotations, description provides sufficient detail. Could mention any rate limits but not essential.

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% description coverage, but description adds value: explains first entity is treated as subject, models parameter details (default vs Anthropic key), and role of context parameter. Goes beyond 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?

Clearly states the tool compares AI visibility across multiple entities, ranks them, and identifies most/least recognized. Distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (more general). Verbs and resource are specific.

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

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

Explicitly suggests competitive AI-marketing audits and gives an example question. Implies usage context but does not explicitly state when not to use or name alternatives. Still clear enough for an agent to decide.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details like partial failures, bundlephobia timing (5-30s), and sources_failed list, providing 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 front-loaded with the core purpose and usage, then details limitations. It is longer but every sentence is informative. Minor conciseness could be achieved by merging some points, but overall it is well-structured.

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

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

Given the tool has two parameters and no output schema, the description covers the return structure (summary block, per-advisory details, links, alternatives) and partial failure behavior. It is fully adequate for the complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by noting that scoped packages (e.g., '@types/node') are accepted, which is not in the schema. However, it does not add significant syntax details beyond what the schema provides.

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

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

The description clearly defines the tool as a composite check for npm packages using deps.dev and bundlephobia, answering questions about safety, popularity, and size. It uses specific verbs and resources, distinguishing it from any sibling tools.

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

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

The description explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also notes the NPM-only limitation and directs to an alternative for other ecosystems.

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 return fields and an example, but does not discuss pagination, rate limits, or behavior with empty queries.

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 and an example: no wasted words. Front-loaded with verb and resource, then example. Excellent conciseness.

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

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

Given no output schema, the description explains return fields well. It could mention pagination (first param) and error handling for no results, but overall it is sufficiently complete for a simple search tool.

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

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

Schema coverage is 100%, so each parameter is documented. The description adds an example demonstrating query and live_only usage, but does not provide additional semantics beyond the schema.

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

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

The description clearly states it searches Twitch channels/streamers by name or keyword, and lists returned fields (display name, game, live status, title, thumbnail). This distinguishes it from sibling tools like get_user (single user) or get_streams (streams not channels).

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

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

The description implies usage for finding channels but does not explicitly state when to use this tool vs alternatives like get_user or get_streams. No guidance on when not to use or prerequisites.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds details about embeddings (BGE-base-en), window size (500-char), char cap (200K), and that longer inputs are truncated and flagged. 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 focused and well-organized: purpose, usage, internal details, pairing, constraints. Every sentence adds value; no wasted words.

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

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

Despite no output schema, description fully explains what is returned (passages with offsets and similarity scores). Covers all input constraints and pairs with a sibling for grounding context.

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

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

Schema coverage is 100%, so baseline 3. Description adds examples for query, explains text is the document, and states limit default (5). Provides meaningful context 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 performs semantic search inside a fetched record, returning relevant passages with offsets and scores. Distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and the use case of large records.

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

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

Explicitly advises when to use: 'when the record is too big to cram into the prompt.' Also explains pairing with ask_pipeworx_grounded and notes the 200K char cap with truncation.

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 idempotentHint=true, readOnlyHint=false, destructiveHint=false. The description adds rich behavioral details: returns subscription id, requires authentication, explains delivery channels with limitations (10/day SMS cap, webhook auto-disable after 10 failures), and required verification steps.

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 lengthy. However, it is well-structured with front-loaded purpose, clear sections for types and delivery, and uses examples effectively. Every sentence adds value, though some internal repetition could be tightened.

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

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

Given the tool's complexity (3 params, nested objects, many sibling tools, no output schema), the description is fully complete. It explains all subscription types, delivery options, constraints, and required prerequisites. The absence of an output schema is compensated by stating returns subscription id.

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

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

Input schema covers parameters with 100% description coverage. The description adds extra meaning by providing type-specific examples and constraints (e.g., phone must be verified, webhook restrictions, signing secret). It clarifies the nested param and delivery objects with concrete usage patterns.

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 creates a proactive monitoring subscription to a live-data event stream, with specific verb ('Create') and resource ('subscription'). It distinguishes itself from siblings like list_subscriptions and unsubscribe by focusing on creation of persistent 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 explains when to use (proactive monitoring) and includes important prerequisites (Pipeworx OAuth, not anonymous/BYO). It does not explicitly state when not to use or name alternatives, but the context of siblings implies the scope.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it returns 'category-bucketed example questions' with 'exact tool + argument shape' and specifies behavior when topic is provided versus omitted, enriching transparency beyond annotations.

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

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

The description is appropriately sized for an onboarding tool, front-loaded with synonyms and usage examples. It is slightly verbose but every sentence adds value without redundancy.

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

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

Given the tool's simple interface (one optional param, no output schema), the description fully covers the purpose, usage, return content, and context (e.g., meta-tools). It is complete for an agent to understand when and how to call 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 one optional parameter. The description adds meaning by listing example topic values ('finance', 'pharma', etc.) and explains the behavior when topic is omitted versus provided, which goes beyond the schema description.

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

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

The description explicitly states it is the 'onboarding entry point' for an agent that just connected, listing multiple synonyms like 'what can I ask Pipeworx?' and clearly states it returns category-bucketed example questions. It distinguishes from siblings by being the first-use discovery 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?

The description says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains how to narrow by topic. While it does not explicitly mention when not to use it or detail all sibling alternatives, the guidance is clear for an onboarding 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 this as read-only, idempotent, open-world, and non-destructive. The description adds that results are ranked by viewers and return specific fields, but it does not disclose additional behavioral traits like rate limits, caching, or authentication behavior beyond what the schema covers. Given the rich annotations, the description provides adequate but not extra transparency.

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

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

The description is a single concise sentence followed by a clear example. Every word is necessary and front-loaded with the core purpose. No redundancy or extraneous information.

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

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

Given no output schema, the description adequately specifies the return fields (game id, name, box art) and ranking method. It could mention the default value of 'first' or the authentication trade-off, but these are covered in the schema. Overall, it is sufficiently complete for a straightforward read-only tool.

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

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

The input schema has 100% coverage, describing both 'first' (number, default 20, max 100) and '_apiKey' (optional string for custom credentials). The description's example ('{ first: 20 }') demonstrates usage but adds no semantic meaning beyond the schema. The baseline 3 is appropriate as the description does not enhance parameter understanding.

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

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

The description clearly states the verb 'Get', the resource 'top games currently being streamed on Twitch', the ranking criterion 'by number of viewers', and the return fields (game id, name, box art). This fully distinguishes it from sibling tools like get_streams which returns streams rather than aggregated game data.

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

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

The description provides no guidance on when to use this tool versus alternatives like get_streams or search_channels. It does not specify prerequisites, such as needing a Twitch API key for higher limits, nor does it explain when the tool should be avoided. The example shows usage but does not clarify scenarios.

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 (non-destructive, mutable), the description adds critical detail: ownership enforcement, deactivation (not deletion), and retention of historical data in 'recent_alerts'. This significantly aids agent understanding.

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 with no wasted words. First sentence states purpose, second adds constraint, third explains effect. Efficient and front-loaded.

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

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

Fully adequate for a simple one-parameter tool with no output schema. Covers action, constraint, and side effects with sufficient detail 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 provides 100% coverage for the single 'id' parameter. Description adds the note that the id comes from 'subscribe', giving agent useful source 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 states 'Cancel a subscription by id' with specifics on ownership and behavior (deactivation vs deletion), clearly distinguishing from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Describes ownership enforcement and deactivation behavior, providing clear context for when to use. Lacks explicit when-not or alternatives, but tool purpose is well-separated from siblings.

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

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

Annotations indicate a read-only, open-world, idempotent operation. The description adds crucial behavioral nuance: the distinction between 'could_not_verify' (check did not happen, must not be treated as evidence) and 'unsupported' (no source covers it), plus the verification_error structure. This goes well beyond the annotations and is essential for correct interpretation of results.

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?

Although the description is lengthy, every sentence carries substantive information: query examples, routing logic, return verdicts, and critical caller caveats. The structure front-loads purpose and usage, then details behaviors and dependencies, with no filler.

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

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

With no output schema, the description carries the full burden of explaining return values, which it does thoroughly by listing all possible verdicts and their meanings, the citation format, and reasoning field. It also covers error handling (verification_error) and the two-tier routing, making it complete for a tool of this complexity.

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

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

Schema already covers both parameters with descriptions (100% coverage), so baseline is 3. The description adds meaningful context for 'tolerance_pct' by explaining it overrides the claim's implied tolerance and how it's used for hallucination detection, and provides concrete examples for 'claim'. This elevates it above baseline.

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

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

The description clearly identifies the tool as a natural-language claim verification tool with a specific verb ('validate') and resource ('claim'). It lists example query phrases and explicitly distinguishes its function from siblings by focusing on fact-checking against authoritative sources.

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 states 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the two distinct execution paths (structured SEC EDGAR for company-financial claims, grounded pipeline for other claims). It also notes it replaces multiple sequential calls, giving clear when-to-use context and efficiency rationale.

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