Twitch

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds cost transparency (BYO key for Anthropic, free default) and details return structure, exceeding what annotations provide.

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

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

Three concise sentences front-load the action, explain parameter nuances, and summarize use cases. No redundancy; 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 no output schema, the description explains return format (per-model fields + combined view). Combined with annotations and schema, it fully prepares an agent for invocation.

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

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

Schema covers all 4 parameters with descriptions (100% coverage). The description adds useful context: default model, API key usage, and context purpose. It enhances understanding without being critical.

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 'probe' and resource 'LLMs', with a specific purpose of scoring visibility (0-100) per model. It distinguishes from siblings like 'scan_competitor_ai_presence' by covering general brand/topic 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?

Explicit use cases are given: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains when to use default vs. Anthropic model. Could be more specific about alternatives, but sufficient for general usage.

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

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

Description adds context beyond annotations: mentions 4,552 tools, 1160 sources, structured answers with citation URIs, and routing behavior. Annotations already indicate read-only, idempotent, non-destructive.

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

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

Thorough with clear sections and examples, but slightly verbose. Could be more concise while retaining 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 broad scope and lack of output schema, description covers purpose, usage, examples, and alternatives 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?

Schema describes question parameter and aliases fully (100% coverage). Description adds minimal additional semantics beyond natural language usage, meeting 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?

Description clearly states it answers questions about current/historical data from many sources, with specific examples. Distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly says 'PREFER OVER WEB SEARCH', provides usage patterns ('what is', 'look up'), and gives step-up alternatives for more specific needs (grounded, deep research).

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds behavioral details: tool selection among 4552 tools, argument filling, data fetching, and extraction only from results. 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 somewhat lengthy but front-loaded with the key phrase 'Hallucination-resistant answer mode'. Every sentence adds necessary context 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?

No output schema, so description compensates by detailing the return structure on success and all possible refusal reasons with explanation, making it complete for high-stakes usage.

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

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

Schema coverage is 100% with descriptions for all parameters including aliases. Description merely reiterates that the question is in natural language, adding minimal value beyond schema.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It distinguishes from the sibling 'ask_pipeworx' by explaining the grounded extraction process and use cases.

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

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

Explicitly tells when to use: when answers will be quoted, cited, or acted on, and the agent must not invent facts. Also advises preferring 'ask_pipeworx' for casual lookups, noting the extra 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?

The description discloses many behavioral details beyond annotations: market resolution, classification, fan-out to data packs, response shapes, resolver contract, parent event extraction, news fallback handling, safety short-circuits, and cancellation rule parsing. Annotations already mark it as read-only, idempotent, and non-destructive; the description adds 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 very long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It contains extensive detail that is valuable for a complex tool, but could be more concise without losing essential information.

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

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

Despite lacking an output schema, the description thoroughly explains the shape of the response (result.market, result.analysis, result.evidence) and key fields like market_match_confidence, parent_event, and news fallback fields. It also covers edge cases (low confidence, closed markets, wide spreads). Nearly complete, but formal output structure is missing.

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

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

Schema description coverage is 100% with clear descriptions for each parameter (market, depth, include_raw). The overall tool description adds context about fan-out behavior but not additional parameter-specific semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: to research a Polymarket bet by pulling Pipeworx data. It specifies the input types (slug, URL, or question text) and the output (evidence packet + market-vs-model comparison), distinguishing it from sibling tools that do general research or data retrieval.

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 suggests use cases: 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. It also provides extensive context on when to inspect market_match_confidence and handle low-confidence matches, but does not explicitly state when NOT to use the tool or list alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds significant behavioral context: it handles off-calendar fiscal years correctly, returns results sorted by primary metric, includes citation URIs, and replaces 8–15 sequential lookups. All traits disclosed align with 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 concisely front-loaded with common query patterns, then states the core function, benefits, and data details. Every sentence adds unique value: usage preference, data sources, fiscal-year handling, sorting, output format, and efficiency claim. No filler or repetition.

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 covers the key aspects: it specifies that results are paired data with citation URIs and sorted. For a tool with two simple parameters, this is largely complete. A minor gap is the exact structure of 'paired data' (e.g., fields per entity), but the provided context suffices for agent execution.

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

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

Schema coverage is 100% but the description adds meaning beyond schema descriptions: it explains what 'company' vs 'drug' types fetch (e.g., revenue, net income, adverse-event counts), gives examples of valid values (tickers/CIKs, drug names), and states that results are sorted. This allows an agent to correctly construct parameter values even without reading the schema.

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

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

The description starts with concrete example queries, immediately clarifying the tool's purpose: side-by-side comparison of 2–5 companies or drugs in one call. It explicitly distinguishes from sequential lookups and explains exactly what data is retrieved for each type (SEC 10-K financials for companies, FAERS data for drugs). This leaves no ambiguity.

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

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

The description explicitly states to prefer this tool over sequential single-entity lookups when comparing entities, and gives example queries like 'which is bigger' that trigger its use. It does not list alternative tools by name but implicitly contrasts with 'entity_profile' (a sibling). The guidance is clear and actionable, though a direct exclusion statement would earn a 5.

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

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

The description discloses important behavioral traits: account requirement, paid plan for certain depth, non-open-web search, parallel tool usage, expected latency (15-60s), and output structure with evidence and gaps. No contradiction with annotations.

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

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

The description is fairly long but well-structured, front-loading critical information like account requirements and alternatives. Every sentence adds value, though slight trimming could improve 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?

Despite no output schema, the description thoroughly explains the return format (findings packet with evidence, confidence, source, etc.), covers input semantics, latency, and alternatives. It is complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces the schema's explanation of the 'depth' parameter but does not add new semantic information beyond what is already in the input schema.

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

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

The description clearly states that the tool performs grounded multi-source research across structured data sources, decomposes questions into facets, and returns a findings packet. It also distinguishes itself from sibling tools like ask_pipeworx.

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

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

The description explicitly tells when to use this tool vs. siblings: use ask_pipeworx for single lookups or breaking news, and avoid if not signed in. It also mentions paid plan requirements for the 'thorough' depth.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by stating that results are 'ready to call directly, no second schema lookup needed' and that it returns 'curated examples.' 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 fairly concise and front-loaded with the main purpose. Each sentence adds value, but it could be slightly more compact by merging the domain list and usage hint. Still 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?

For a discovery tool with one required parameter and no output schema, the description adequately explains what the tool does, what inputs it accepts, and what outputs to expect. It feels complete.

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

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

Schema coverage is 100% with detailed descriptions for each parameter. The description does not add significant meaning beyond the schema, but it does confirm that the tool accepts natural language and multiple aliases. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It explicitly lists domains (SEC filings, financials, etc.) and distinguishes from sibling tools by focusing on discovering which tool to use rather than directly searching 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 explicit guidance: 'Use when you need to browse, search, look up, or discover what tools exist for' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells when to use it and implicitly when not.

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 discloses fan-out behavior across multiple sources, specific return fields, patent sunset, and name limitation. No contradiction with annotations (readOnlyHint, etc.). Adds 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?

Single dense paragraph covering all key info; no waste. Could be more structured (e.g., bullet list) but remains readable and efficient for the volume of detail.

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 thoroughly explains return content (filings with URIs, fundamentals sorted, patent status, news fallback, LEI) and constraints (only company type). Complete for a complex tool.

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

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

Schema already covers parameters with 100% description coverage. Description reinforces that value can be ticker or zero-padded CIK and that names are not supported, adding slight extra 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 states specific verb+resource ('full cross-source profile of a US public company') and distinguishes from siblings like resolve_entity and compare_entities. It lists exact data sources and return fields, making purpose unmistakable.

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

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

Explicitly states when to use ('ALWAYS PREFER over chaining... for holistic view') and when not to ('names not supported — use resolve_entity first'). Provides clear alternative guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's mention of 'Delete' is consistent. However, it does not add further behavioral context about side effects or irreversibility beyond what annotations provide.

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

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

The description is two sentences: the first states the core purpose, the second provides usage guidelines. It is front-loaded, efficient, and contains no superfluous words.

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

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

For a simple delete operation with one parameter, annotations, and no output schema, the description sufficiently covers purpose, usage, and relationships. It could mention behavior for missing keys, but the idempotent hint mitigates that need.

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

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

The parameter 'key' is fully described in the schema (100% coverage) as 'Memory key to delete'. The description only adds 'by key' which is redundant with the schema. No additional semantic value is provided.

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 'Delete a previously stored memory by key.' This uses a specific verb (delete) and resource (memory), and distinguishes it from sibling tools 'remember' and 'recall' which are store/retrieve 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 lists when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also suggests pairing with siblings 'remember and recall', providing clear context for use.

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

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

Annotations declare read-only, open-world, idempotent, non-destructive. Description adds that it fetches pages, extracts content, and emits a markdown blob. No contradictions; the description enriches behavioral 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 concise sentences: purpose, process, output+uses. Front-loaded with key terms. Zero 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?

Covers purpose, process, output format, and use cases. Lacks error handling details (e.g., invalid URL handling) but given simple tool and rich annotations, it is sufficiently 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 covers both parameters fully. Description does not add extra semantic detail beyond what schema already provides (e.g., no explanation of defaults or constraints). Baseline 3 is appropriate.

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

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

Clearly states verb 'generate' and resource 'llms.txt file for any URL'. Distinguishes from siblings by specifying unique output format and use cases. No ambiguity.

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

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

Lists explicit use cases (client indexing, own project drafting, competitor auditing). Does not provide when-not-to-use or compare directly to siblings, but the context is clear enough for selection.

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

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

Annotations already cover safety (readOnly, idempotent). Description adds value: automatic game-to-id resolution, return fields, and _apiKey for higher limits.

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

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

Two concise sentences plus a clear example. Front-loaded with core purpose. No redundant information.

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

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

No output schema, but description lists return fields. Covers all parameters with additional context. 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%, baseline 3. Description adds example usage, default/max for 'first', and explains automatic resolution for 'game'. Exceeds 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?

Description clearly states it retrieves live Twitch streams, with optional filtering and specifies return fields (streamer name, title, viewer count, thumbnail). Differentiates from sibling tools like top_games and 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 clear usage hint: omit 'game' for overall top streams. Lacks explicit when-not or alternatives, but context is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by specifying the returned fields and the reliance on Twitch API, providing behavioral context beyond annotations.

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

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

The description is concise: two sentences plus an example. No unnecessary words; every part 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 this is a simple read-only lookup with well-documented parameters and rich annotations, the description is complete. It lists return fields and provides an example, meeting the needs for proper 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 description coverage is 100%, so baseline is 3. The description adds meaning with an example usage and reinforces that 'login' is the username, which improves clarity 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 clearly states the tool looks up a Twitch user/channel by login (username) and lists the returned profile fields. It includes an example, which differentiates it from siblings like 'get_streams' that handle different resources.

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 the tool is used for retrieving user info by login. It does not explicitly state when not to use or mention alternatives, but the purpose is sufficiently clear for the agent to choose it appropriately.

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 value by specifying return fields and mentioning the optional parameter, complementing the annotations well.

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 that are efficient and front-loaded with the core action. No redundant language.

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 one optional parameter, no output schema, and clear annotations, the description provides complete context for usage. It could mention if there is pagination, but given the tool's simplicity, it is sufficient.

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

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

Schema coverage is 100% with a clear parameter description. The description does not add extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', giving clear when-to-use guidance.

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

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

Discloses behavioral traits beyond annotations: rate limit (5 per identifier per day), no quota count, team reads daily, and signal affects roadmap. No contradiction with annotations.

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

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

Concise yet comprehensive, with clear structure: purpose, usage criteria, formatting guidance, and limitations. 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 simplicity (3 params, no output schema), the description covers all necessary aspects: what to submit, how to format, constraints, and post-submission expectations.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds value by advising to describe issues in terms of Pipeworx tools/packs and not paste user prompts, which enhances understanding beyond schema.

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

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

The description clearly states the tool's purpose: sending feedback about bugs, features, data gaps, or praise. It distinguishes from sibling tools like ask_pipeworx by focusing on feedback rather than asking questions.

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

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

Explicitly specifies when to use each feedback type (bug, feature, data_gap, praise) and what to avoid (pasting end-user prompts). Also mentions rate limits and that it's free, providing clear context for when 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?

Annotations already indicate read-only and idempotent. Description adds sourcing (CF analytics), no PII, counting behavior, and caching window (5min-1h). No contradictions; adds value beyond annotations.

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

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

Concise yet packed: first sentence states output, then bullet-like use cases, then technical details. Every sentence serves a purpose 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 full schema coverage and annotations, the description covers purpose, usage, behavior, and parameter. Minor gap: no mention of result format or limits, but not critical for a simple trending endpoint.

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?

Single parameter 'window' with enum. Description explains that shorter windows show current hot items and longer windows show steady-state demand, adding meaningful guidance beyond the schema.

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

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

The description explicitly states it returns top tools, packs, and call volume over a time window. It lists concrete use cases, clearly distinguishing it from sibling tools like discover_tools or ask_pipeworx.

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

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

Provides explicit contexts for when to use (discovering hot sources, confirming canonical tool, checking alignment). Does not include when-not-to-use or alternatives, but the use cases are clear and 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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral context: monotonicity checks, partition sum check, semantic anchor (threshold), partition filter (placeholder slugs), fill check against live CLOB depth. 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 long but well-structured with clear sections for each mode and important details like semantic anchor, partition filter, fill check. Every sentence adds value, though some redundancy could be trimmed. Front-loaded with 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?

Given the complexity (multiple modes, checks, fill check sub-system), the description is very complete. Covers input semantics, internal logic, output structure, and practical warnings. References sibling tool for further detail. No output schema, but description explains return format sufficiently.

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 descriptions for both parameters. The description adds significant meaning beyond schema: explains the difference between event and topic modes, provides examples of slugs, and notes that full URLs are accepted. Compensates fully.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes: trending_scan (no args), event (single market slug), and topic (cross-event). Very specific verb+resource+scope.

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

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

Explicit guidance for each parameter: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also mentions when not to trade via fill_check and references polymarket_fill_risk for custom sizing.

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

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

Beyond annotations (readOnlyHint, etc.), the description discloses extensive behavioral traits: model families, edge calculation, caching policy, output structure with segments and diagnostics, and tradeable-edge knobs. No contradictions with annotations.

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

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

The description is well-structured with clear sections but is verbose. While front-loaded with the purpose, the lengthy details on model families and diagnostics could be condensed for an AI agent without losing essential information.

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

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

Given the tool's complexity (9 parameters, 3 model families, caching, diagnostics), the description covers all necessary aspects: edge calculation, output structure, filter behaviors, and edge cases like Fed bets. Without an output schema, the description provides complete 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%, and each parameter has a description in the input schema. The tool description does not add parameter-level semantics beyond what is already provided, meeting the baseline expectation.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is specific about the verb, resource, and scope, and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on model-driven and structural discrepancies.

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

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

The description explicitly states the tool is built for 'what should I bet on today' and helps agents discover opportunities without paging hundreds of markets, providing clear context. However, it does not explicitly mention when not to use it or list alternative tools, which would improve 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?

Beyond annotations (readOnlyHint, etc.), the description discloses key behaviors: reads from daily snapshots with a 60-day TTL, decay numbers from daily closes not intraday, and snapshot gaps when polymarket_edges has cache misses. This adds significant 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 front-loaded with the core purpose and then details the response structure. It is somewhat lengthy but every sentence provides necessary context. Minor redundancy exists (e.g., repeating default values) but overall efficient.

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

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

Given no output schema, the description thoroughly explains the response fields (tracked[], expired[], snapshot_dates[]) with their meanings. All parameters are covered, and operational constraints (TTL, snapshot gaps) are included. This makes the tool fully understandable without external 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 description coverage is 100% with clear descriptions for both parameters. The description adds value by specifying defaults (days=14, window='1wk') and limits (days max 30), which exceed the schema's information and aid correct invocation.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots, answering a specific question about edge age and decay. It distinguishes from the sibling tool 'polymarket_edges' by focusing on time-series analysis rather than current states.

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 implicitly guides usage by contrasting fresh vs. old edges ('a fresh wide edge and a 3-week-old wide edge are different trades'), indicating when this tool is valuable. However, it does not explicitly state when not to use it or provide direct comparisons to alternatives beyond the implication.

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 mark it readOnly, idempotent, non-destructive. The description aligns fully, emphasizing it is a check (not a mutation) and details the output (order book walks, fill metrics, verdict). Describes the risk of partial fills, which is critical behavioral context beyond annotations.

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

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

The description is lengthy but well-structured with sections for single-market, basket, and a usage warning. Every sentence adds value. Slightly verbose but organized, earning a 4.

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 enumerates every return field for both modes, explains risk of partial fills, and provides context for the forced_directional_risk. Annotations cover safety. The definition is fully complete for a risk-check 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%, baseline 3, but the description adds significant semantics: dual-mode logic for parameters, interpretation of side per mode, different meaning of size_usd for buys vs sells, and defaults/clamping. This far exceeds 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 precisely states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' with two clear modes (single-market and basket). It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly instructing to use it before acting on those signals.

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: requires one of market or event, explains defaults for side and size_usd, and warns that partial basket fills convert arbs into directional positions. It states exactly when to use this tool (before arb signals or edges trades above ~$500).

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

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

Annotations indicate readOnly, idempotent, non-destructive. The description adds significant behavioral detail: compatibility_warning conditions, temporal_alignment checks, and skipped_cross_type/subtype counters. No contradiction with annotations.

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

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

The description is fairly long but well-structured with bullet points, bolded terms, and clear sections. It front-loads the core purpose and then systematically explains modes, response structure, and safety fields. Every sentence adds value, though slight trimming could improve 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?

Despite the absence of an output schema, the description fully explains the response: leg-by-leg prices, spread array, safety fields, and compatability warnings. It also addresses edge cases like temporal misalignment and non-equivalent bet shapes, making it complete for complex usage.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value by explaining the two modes, the list of topic shortcuts, and that explicit tickers override topic mapping. This enhances understanding beyond the schema.

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

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

The description clearly states it computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It specifies two distinct modes (topic shortcuts and explicit tickers) and details the output structure. While sibling tools exist like polymarket_arbitrage, the unique cross-venue focus is evident.

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

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

The description explains when to use the tool (comparing prices across venues) and, importantly, when spreads are not meaningful via compatibility_warning and temporal_alignment. It does not explicitly name alternative tools but provides clear context for correct usage.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds useful context: scoping to identifier and pairing with remember/forget. This goes beyond what annotations provide without contradicting them.

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

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

The description is concise at 4 sentences, well-structured: first sentence states purpose, second gives use cases, third mentions scoping, fourth mentions sibling tools. No unnecessary words.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers purpose, usage, scoping, and relationships with sibling tools completely. No gaps remain.

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

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

Schema coverage is 100% and the description adds value by explaining the effect of omitting the key (list all keys) and providing examples of typical stored values. This clarifies the parameter's role 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 clearly states the verb (retrieve/list) and resource (previously saved memories), and distinguishes from sibling tools 'remember' and 'forget' by explicitly mentioning them. It also notes the optional behavior of listing all keys when the argument is omitted.

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 concrete examples of when to use the tool (look up user's target ticker, address, research notes) and mentions scoping. While it doesn't explicitly state when not to use it, the context is clear enough to guide appropriate use.

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

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

The description discloses the behavioral effect of 'mark_read:true' which flags events as read, implying a state change. This conflicts with the 'readOnlyHint' annotation, which suggests no modifications. The description is transparent but the contradiction reduces reliability.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence adds value. No unnecessary words or redundancy.

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

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

Despite no output schema, the description specifies the return structure (source, citation_uri, payload). It also covers polling behavior and alternative access, making it complete for this type of tool.

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

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

The description enriches each parameter beyond the schema, e.g., explaining 'type' with an example ('sec_8k'), specifying 'since' as ISO timestamp, and clearly defining the effect of 'mark_read'. With 100% schema coverage, it adds significant value.

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: 'Pull fired events from your subscription feed' and describes the return data. It distinguishes itself from sibling tools like 'get_streams' and 'list_subscriptions' by focusing on fired events.

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 guidance on when to use the tool ('Polls work fine') and mentions an alternative access method (GET registry.pipeworx.io/alerts.json). However, it does not explicitly state when not to use this tool or compare with all 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 declare readOnlyHint and idempotentHint, and the description adds behavioral details not in annotations: fan-out to multiple sources, GDELT→GNews fallback on rate limits/5xx, USPTO soft-fail until reactivated. No contradictions.

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

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

The description is moderately long but efficiently structured: starts with query examples, then succinctly explains sources, parameters, and alternatives. Every sentence adds value, though slight trimming of fallback details could improve 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 the tool's complexity (multiple sources, fallbacks, API sunsets) and no output schema, the description is thorough. It explains the return structure (grouped changes, total_changes, citation URIs) and handles edge cases like PatentsView API soft-fail.

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

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

Schema coverage is 100%, and the description adds meaning beyond enum values and types: it explains that 'since' accepts ISO or relative shorthand ('7d', '30d', '3m', '1y'), and 'value' can be ticker or CIK with example. This clarifies 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 defines the tool as a change feed for a company over a time window, with example queries like 'What's new with X' and explicit mention of sources (SEC, news, patents). It also distinguishes itself from entity_profile.

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

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

The description provides explicit guidance: use this tool for time-windowed changes and entity_profile for static profiles. It also gives parameter hints like 'Use "30d" or "1m" for typical monitoring'.

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 useful context beyond annotations: scoping by identifier, persistence for authenticated users vs 24-hour retention for anonymous sessions. Annotations already indicate idempotentHint=true and destructiveHint=false, and description does not contradict them.

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

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

The description is well-structured, starting with the core purpose, then examples, then technical details. It is concise with no wasted sentences, but could be slightly more compact.

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 important aspects: key-value storage, scoping, persistence duration, and pairing with recall/forget. It does not specify the return value or overwrite behavior, but idempotentHint covers that.

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

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

Schema coverage is 100%, so description adds minimal new info. It provides usage examples (e.g., 'subject_property') but that is already in schema. No additional syntax or constraints beyond the schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It specifies the action (save), resource (key-value pairs), and distinguishes from sibling tools recall and forget.

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

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

The description provides clear guidance on when to use (when discovering something worth carrying forward) and lists examples. It implicitly suggests alternatives by mentioning recall and forget, but does not explicitly state 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that the tool cascades through several endpoints internally and provides citation URIs, which gives useful behavioral context beyond the annotations.

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

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

The description is front-loaded with examples and structured well, though slightly lengthy. Every sentence adds value, and the format using bullet points for supported types improves readability.

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

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

Given the complexity of handling two entity types with different identifier systems, the description covers all necessary aspects: purpose, usage, parameter details, return information, and internal behavior. It is 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 two parameters. The description adds examples of valid inputs (ticker, CIK, name for company; brand/generic for drug) and explains the output structure for each type, enhancing understanding beyond the schema.

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

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

The description clearly states it resolves user-spoken names to canonical identifiers. It provides example queries and lists supported entity types with specific return formats. While sibling tools like entity_profile exist, the description makes its unique purpose evident.

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 FIRST whenever you have a name but need an ID.' It also mentions internal cascading behavior, replacing manual lookups. It does not explicitly state when not to use it, but the context is 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 indicate readOnly, openWorld, idempotent, non-destructive. Description adds that it internally probes with ai_visibility_check, ranks, and returns per-entity metrics (score, confidence, signal density), providing valuable behavioral context beyond annotations.

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

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

Four sentences, front-loaded with primary action, no extraneous words. Every sentence adds value: purpose, method, use case, return format.

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 safe annotations, no output schema, and 4 params fully described in schema, the description adequately explains the process, internal calls, output structure, and use case. Minor gap: does not mention output schema details, but not required.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions probing entities but does not add new meaning beyond the schema for models, _apiKey, or context. No contradiction or omission.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes with ai_visibility_check, ranks, and returns a ranked list. It distinguishes from sibling ai_visibility_check by focusing on multiple entities.

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

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

The description says 'Useful for competitive AI-marketing audits' and implies it is for when you need to compare multiple entities, distinguishing from single-entity checks. It does not explicitly state when not to use, but context with sibling tool provides clarity.

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 readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds valuable context beyond annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed will list timeouts. 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 bullet-like lists and parentheticals. It could be slightly more streamlined, but every sentence adds value and is front-loaded with the core 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?

No output schema exists, so the description must explain return values. It does so thoroughly: summary block fields, per-advisory detail, links, and alternative versions. It also covers ecosystem scope and error behavior.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context: scoped packages accepted (@types/node), version defaults to latest, and the purpose of each parameter is implied. This extra clarification justifies a 4.

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

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

The description clearly states it's a composite check for npm packages, covering license, advisories, version history, bundle size, and tree-shake support. It specifies the exact use case: answering safety, popularity, and cost questions. This distinguishes it from sibling tools like 'validate_claim' or 'compare_entities'.

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

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

Explicitly tells when to use: when an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also provides exclusions: NPM only in v1; other ecosystems fall under deps.dev:version directly.

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

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

Annotations already indicate safe read-only, idempotent operation. The description adds value by detailing the return fields and demonstrating usage with an example, but does not cover potential rate limits or pagination details beyond the 'first' 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 an example, with no extraneous words. It is front-loaded with the main action and returns immediately.

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

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

Given the tool has 4 parameters, no output schema, and annotations, the description adequately explains what it returns and provides an example. Missing pagination details beyond 'first' is minor.

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 describes all parameters (100% coverage). The description adds a concrete example showing how to use query and live_only, and clarifies the purpose of '_apiKey'. This adds meaning beyond the schema definitions.

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

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

The description explicitly states the tool searches Twitch channels/streamers by name or keyword, lists the returned fields, and gives an example. This clearly distinguishes it from sibling tools like get_streams or get_user.

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 an example usage and mentions the live_only filter, giving clear context for when to use it. However, it does not explicitly state when not to use it or contrast with alternatives.

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

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

Annotations already provide readOnly, idempotent, non-destructive hints. The description adds specific technical details: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag, and that each passage includes offset and similarity score. No contradictions.

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

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

Four sentences that are front-loaded with the core purpose, then add detail on use case and technical behavior. No fluff or repetition. Efficient and easy to parse.

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

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

Tool has 3 parameters, no output schema. Description explains return format (passages with offsets and similarity scores), cap and truncation behavior, and embedding model. Covers all essential behavioral aspects for an AI 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%, baseline 3. The description enriches parameters by providing example queries for the 'query' param and clarifying 'top-N passages' for 'limit'. The 'text' param already has a clear description in schema. Overall adds value beyond schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and provides concrete examples (SEC 10-K, article, tool result). It distinguishes from siblings by referencing ask_pipeworx_grounded and specifying that it works on already-fetched text.

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 the record is too big to cram into the prompt' and describes how it saves context. Mentions pairing with ask_pipeworx_grounded for a workflow. However, it does not give explicit when-not-to-use or directly name 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?

Annotations indicate mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds critical behavioral details: OAuth requirement, type-specific parameterization, delivery options, webhook signing secret, SMS cap, and auto-disable for webhooks. No contradictions with annotations.

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

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

The description is well-structured: purpose first, then supported types with examples, then delivery channels. It is lengthy but every sentence adds necessary detail. Slightly verbose for a 1-5 scale, but still efficient for the information density.

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

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

Despite no output schema, the description fully explains the tool: what it creates, the required auth, type-specific parameters, delivery options, and return value (subscription id). It provides complete context for an agent to decide and invoke correctly.

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

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

Schema coverage is 100%, but the description adds significant meaning by explaining each type's params with examples (e.g., 'sec_8k: {ticker:"AAPL", items?:["5.02"]}') and delivery constraints (e.g., 'sms: must match verified phone, 10/day cap'). This goes beyond the schema's bare descriptions.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This specifies the verb (create), resource (subscription to event stream), and output (subscription id), distinguishing it from siblings like 'unsubscribe' and 'list_subscriptions'.

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

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

The description provides extensive usage context: requires Pipeworx OAuth account, lists supported types with examples, and details delivery channels with constraints. It implicitly tells when to use (to set up monitoring) and when not (e.g., if no OAuth account), though it could explicitly contrast with read-only alternatives like 'recent_alerts'.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context that the tool returns category-bucketed examples from a live catalog of thousands of tools, which goes beyond the annotations without contradicting them.

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

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

The description is comprehensive but slightly lengthy. It front-loads key trigger phrases and provides necessary detail about the return content. Every sentence adds value, but it could be slightly more concise without losing clarity.

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

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

Even without an output schema, the description fully explains what the tool returns: category-bucketed example questions with tool+argument shapes. Given the tool's purpose (onboarding), this is complete and addresses the user's likely needs.

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

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

Schema has 100% coverage with a description for the optional topic parameter. The description explains that omitting topic gives a full cross-category spread, and lists example values (e.g., 'finance', 'pharma'), adding meaning beyond the schema's enum-like hints.

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

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

The description clearly states it is an onboarding entry point, listing trigger phrases like 'What can I ask Pipeworx?' and specifying it returns category-bucketed example questions with tool+argument shapes. It distinguishes from sibling tools by mentioning meta-tools like ask_pipeworx and entity_profile.

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

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

The description explicitly says to use this when you do not yet know what Pipeworx can do, or to learn how to call meta-tools. It also explains the optional topic parameter for focus. It does not explicitly state when not to use, but the context is sufficiently clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds that results are current and limited to games being streamed, but does not disclose details like rate limiting or data freshness windows. Given the rich annotations, the description is adequate but not enhanced.

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

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

The description is extremely concise: two sentences plus an example, front-loaded with action and result. Every word adds value with no redundancy.

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

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

For a simple read-only tool with no output schema, the description is complete: it states what is returned (id, name, box art) and how parameters work. No gaps given the low 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% (both parameters fully described in schema). The description adds an example usage but no new semantic meaning beyond what the schema provides, so baseline 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 the tool gets top games on Twitch ranked by viewers, with specific return fields (id, name, box art). This distinguishes it from sibling tools like get_streams which focus on streams.

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 an example call with the 'first' parameter, implying usage. However, it does not explicitly state when to use this tool over alternatives like search_channels or get_streams, though the context makes it reasonably 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?

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds that ownership is enforced and that the row is deactivated (not deleted), so historical events persist. This provides key behavioral context.

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

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

The description is two sentences, efficient, and front-loaded with the main action. 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?

For a simple tool with one parameter and no output schema, the description covers purpose, usage conditions (ownership), and behavioral outcome (deactivation, historical availability). It is complete for an agent to select and invoke correctly.

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

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

The schema describes the parameter 'id' as a subscription uuid returned by subscribe. The description adds that ownership is enforced, meaning you can only use ids for your own subscriptions, providing critical context beyond the schema.

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

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

The description clearly states it cancels a subscription by id, with specific verb 'Cancel' and resource 'subscription'. It distinguishes from sibling tools like subscribe and list_subscriptions by indicating it is for cancellation and deactivation rather than creation or listing.

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 mentions ownership enforcement (only cancel own subscriptions) and that the row is deactivated, not deleted, so historical events stay available via recent_alerts. This guides when to use it but does not explicitly compare with other tools like subscribe or list_subscriptions.

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, openWorldHint, and destructiveHint=false. The description adds behavioral context beyond that: it details the return verdict types, structured form, actual value with citation, percent delta, and notes it replaces multiple calls. It also transparently scopes to company-financial claims. This provides useful transparency without contradicting annotations.

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

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

The description is three sentences long, front-loaded with example user phrases, then states purpose, scope, return format, and value proposition. Every sentence adds information, though it could be slightly more concise. Overall well-structured and efficient.

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

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

Given the tool's moderate complexity (NL claim verification with a single parameter and no output schema), the description is complete enough. It covers what the tool does, when to use it, its scope, and what it returns. It doesn't cover error cases or performance, but that is acceptable for this level of 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% for the single 'claim' parameter, so baseline is 3. The description does not add significant new semantics beyond the schema; the schema already describes it as a natural-language factual claim with examples. The description's examples are helpful but not necessary for understanding the parameter.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It uses specific verb-resource ('validate claim'), provides example phrases that users might say, and distinguishes itself from siblings by specifying its domain (company-financial claims via SEC EDGAR) and noting it replaces multiple sequential calls, indicating a unique utility.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies the supported claim type (company-financial for public US companies). While it doesn't explicitly mention when not to use, it provides clear guidance on appropriate contexts.

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