Zendesk

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds valuable context: default model is free, using Anthropic requires BYO key and direct payment, and the return structure includes per-model metrics. 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 a single paragraph of 3 sentences, front-loaded with the main action and use cases, followed by clarifying details. No wasted words.

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

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

Given 4 parameters and no output schema, the description compensates by explaining the return structure, default model, key requirement, and use cases. It provides enough context for an agent to invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds further meaning by explaining the default model, how _apiKey works, and the return format (per-model {score, confidence, signals, raw_response} + combined view), which goes beyond the schema.

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

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

The description clearly states 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It uses a specific verb (probe) and resource (LLMs, visibility), and distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on generic brand checking with scoring.

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

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

The description provides explicit use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' However, it lacks explicit when-not-to-use or mention of alternatives among the many sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context beyond these: it routes to 5,562 tools across 1,462 sources, fills arguments, returns stable citation URIs, and works on every tier. This goes beyond the annotation safety profile without contradicting it.

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 and front-loaded with the key instruction to prefer it over web search. While it lists many domains and examples, each segment serves a purpose, and the text is organized logically from directive to mechanism to examples to alternatives. It is not overly verbose for the complexity it covers.

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 (5,562 tools, many domains), the description covers all necessary context: return format (structured answers with pipeworx:// citations), when to use it (most questions), when not to (breaking news still works via routing), and alternatives. The lack of an output schema is compensated by the description's clear statement of what the tool returns.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for 'question'. The description enriches this by providing many realistic example questions (e.g., 'current US unemployment rate', 'Apple's latest 10-K'), clarifying the expected input format and range of acceptable queries beyond the generic schema description.

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

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

The description clearly states the tool routes questions to relevant tools and returns structured answers with citations. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, and enumerates supported domains, so the agent knows exactly what this tool does.

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

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

The description provides explicit guidance on when to use this tool vs alternatives: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and specifically says to use ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad multi-part questions. It also gives example questions, making usage context unambiguous.

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 critical behavioral context beyond the annotations by disclosing that experimental routing candidates may be enabled live, that no candidate is currently active as of 2026-07-26, and that it currently matches ask_pipeworx exactly. This transparency about its dynamic, experimental nature is valuable and not captured by the readOnlyHint or idempotentHint annotations.

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

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

The description is four sentences and front-loaded with the essential identity of the tool. It avoids fluff, but there is slight redundancy in emphasizing 'this IS a full working router' after already calling it an identical universal router. Still, every sentence earns its place.

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

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

Given the tool's complexity as an experimental beta router, the description covers identity, current state, usage conditions, and functional guarantees. It explicitly mentions 'same response shape' as ask_pipeworx, which compensates for the lack of an output schema. The description is sufficiently complete for an agent to decide when and how to use it.

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

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

The schema covers 100% of parameters, all six of which are aliases for 'question'. The description adds no new parameter-level semantics beyond stating 'same arguments' as ask_pipeworx, so the baseline score of 3 is appropriate—the schema already handles the burden.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, functioning as an identical universal router with the same 5,562 tools, arguments, and response shape. It distinguishes itself from the stable sibling by emphasizing its experimental edge, so the purpose is specific and well-differentiated.

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

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

It explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing', providing a clear condition for when to choose this tool over the stable alternative. The mention that results are compared against the stable router further reinforces the intended usage context.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral detail: it reveals the exact success return shape, the refusal_reason enum values, and the mechanism of grounding to the tool result. It also warns about the extra LLM call cost, which is not in the annotations. This goes far 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 dense but well-structured. The first sentence establishes intent, the second explains the process and return object, the third lists refusal reasons, and the fourth gives use cases and the cost comparison. Every sentence carries unique information, and the use of dashes and braces aids scanning. No filler 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?

For a tool with no output schema, the description fully documents both success and refusal return structures, including the enum of refusal reasons. It also provides performance context (extra LLM call), usage boundaries, and sibling differentiation. Given the complexity of the tool, this description is remarkably 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 six aliases for a single natural-language question. The schema already describes the question parameter and its aliases clearly. The description does not add parameter-specific semantics; it only mentions that the tool internally 'fills arguments,' which is about routing, not the input parameter. Thus a baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' which is a specific verb+resource comb with a clear scope. It explicitly distinguishes from the sibling ask_pipeworx by noting 'Same routing as ask_pipeworx' but then 'EXTRACTS the answer using ONLY what the tool result contains,' showing a unique behavior. The mention of high-stakes uses (financial, legal, medical) further pins down its purpose.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives a clear exclusion with 'prefer ask_pipeworx for casual lookups' and explains the tradeoff (one extra LLM call). This is strong for both when and 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?

Discloses behavioral traits beyond annotations: market resolver, fan-out logic, response shapes (market_match_confidence, parent_event, news fields), safety low-confidence short-circuit, closed market handling, wide spread warning, resolution-rule risk. No contradiction with annotations (readOnly, idempotent, openWorld).

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 long (~600 words) but highly informative and well-structured. Front-loaded with purpose, then detailed breakdowns. Each paragraph has a clear function (classifiers, fan-out, response shapes, safety, resolution rules). Could be slightly trimmed but no wasted words for the complexity.

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

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

Given 3 params, 1 required, no output schema, and rich annotations, the description covers all necessary context: input handling, resolution process, data sourcing, blocking conditions, response fields, and edge cases. Completely adequate 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 100% with good descriptions. Description adds significant context: input format variations for 'market', depth parameter behavior elaborated, include_raw payload size details. Adds value beyond schema for all three parameters.

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

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

The description clearly states the tool researches a Polymarket bet by pulling relevant Pipeworx data, with specific input formats (slug, URL, question text) and output (evidence packet + market-vs-model comparison). It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on 'should I bet on X' 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 states use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides classifiers and fan-out examples. However, does not explicitly mention when not to use or compare to siblings like polymarket_edges for edge analysis.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds rich behavioral context: results sorted by primary metric, data sources (SEC/FDA), handling of off-calendar fiscal years, and output format (paired data + URIs). This goes well 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 relatively long but front-loaded with example queries and a clear recommendation. Each sentence adds value, though some minor redundancy (e.g., 'side-by-side' and 'comparison') could be trimmed. Overall well-structured.

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

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

Given the tool's low complexity (2 params, no output schema), the description adequately covers inputs, outputs (sorted, paired data, URIs), data sources, and edge cases (off-calendar years). With annotations covering safety, 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 coverage is 100%, but the description adds meaning: for 'type', it explains what data each enum value pulls; for 'values', it specifies input formats (tickers/CIKs for companies, drug names) and provides examples. 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 performs side-by-side comparison of 2–5 companies or drugs in one call. It uses specific verbs like 'compare' and 'rank', and explicitly distinguishes from sequential single-pack lookups, which are sibling-adjacent actions.

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

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

The description strongly recommends using this tool over sequential lookups when comparing entities, and provides example queries. However, it does not explicitly mention when not to use it (e.g., for more than 5 entities or non-entity comparisons), though the schema's maxItems imposes a limit.

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

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

Adds rich behavioral context beyond the readOnly/openWorld/idempotent annotations: account/pricing requirements, parallel routing to 5,562 tools, output packet structure (verbatim evidence, confidence, source, fetched_at, citations), explicit mention of gaps[] ('never invented'), depth-level hit behavior (gap recovery and lead chasing), contradictions[] scans, semantic excerpting, and latency. 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 long (~300 words) but information-dense, covering many distinct aspects: auth, purpose, alternatives, output format, depth behaviors, and latency. It is front-loaded with the account requirement and core purpose, though the single-paragraph stream-of-consciousness structure could be more scannable with bullet points.

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

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

With no output schema, the description fully explains return contents: findings packet, gaps[], contradictions[], hop field, citation_uri, and semantic excerpting. It also covers prerequisites (sign-in), pricing, latency, and when results are likely empty (non-catalog topics). This is complete enough for an agent to invoke correctly without further 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 documents both parameters fully (100% coverage), giving a baseline of 3. The description adds contextual meaning: question may be broad/multi-part and decomposition is the point; depth:'thorough' is paid; latency varies by depth ('Expect 15-60s (thorough ... up to ~90s)'). These enrich the parameter semantics without being redundant.

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 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' and clarifies 'this is NOT open-web search.' It further states 'Decomposes your question into focused facets, routes each to the right one of 5,562 tools IN PARALLEL, and returns a findings packet.' This clearly distinguishes it from sibling ask_pipeworx ('For a single lookup use ask_pipeworx').

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

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

Explicitly states 'Best for broad/multi-part questions over structured data' and gives examples. It names alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx.' It also provides an account-based exclusion: 'If you are not signed in, use ask_pipeworx instead.'

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so no contradiction. Description adds that it returns top-N tools with full schemas, which is consistent with safe, idempotent behavior. No additional safety or side-effect context needed 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?

Description is well-structured, front-loading the purpose and usage, then detailing output and when to use. Every sentence is informative without redundancy, appropriate length for the complexity.

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

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

Given no output schema, the description fully explains the return value (top-N tools with names, descriptions, schemas). With 6 parameters and 32 siblings, it addresses usage, limitations, and output format 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 coverage is 100%, and each parameter already has a description. The description does not add new semantic info beyond what's in the schema, meeting the baseline but not exceeding it.

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

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

Description clearly states it finds tools by describing a data or task, and lists many specific domains (SEC filings, financials, etc.), distinguishing it from sibling tools like deep_research or search_within which focus on content retrieval rather than tool discovery.

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

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

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set,' and lists contexts like browsing, searching, and discovering tools for specific categories, providing clear guidance on when to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it fans out across multiple sources, returns specific fields, notes the USPTO sunset issue (soft-fails), and describes fallback behavior (GDELT -> GNews). This goes beyond annotations, though some details (like response format) are omitted.

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 a clear goal. It is somewhat verbose but every sentence serves a purpose (use cases, return fields, constraints). Could be slightly tighter, but structure is logical and easy to scan.

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

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

Despite having no output schema, the description thoroughly explains what the tool returns: cik, company_name, recent_filings with URIs, fundamentals, patents status, news sources, and LEI. It also covers edge cases (patents sunset, name unsupported). For a complex multi-source profile tool with 2 required params, this is 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% (2 parameters both described). The description adds meaning beyond schema: clarifies that 'value' accepts ticker or CIK but not names, and that 'type' is limited to 'company'. It also hints at future support for person/place. This enriches 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 clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call'. It uses specific action verbs like 'brief me' and 'research' and lists the integrated sources (SEC, XBRL, USPTO, news, GLEIF). This strongly distinguishes it from siblings like 'resolve_entity' and 'compare_entities'.

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

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

Explicitly states when to use: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. Also specifies when not to use: 'names not supported (use resolve_entity first if you only have a name)'. This provides clear guidance on tool 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 indicate destructive and idempotent behavior. Description adds context about clearing sensitive data, but no further behavioral details beyond what annotations imply.

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

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

Two concise sentences, front-loaded with purpose, no unnecessary words. Each sentence adds value.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage guidelines, and relationships adequately.

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

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

Schema coverage is 100% and parameter description ('Memory key to delete') is clear. The description does not add additional meaning beyond the schema.

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

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

Clearly states 'Delete a previously stored memory by key', specifying verb, resource, and method. Mentions pairing with siblings remember and recall, distinguishing it.

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

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

Explicitly provides usage scenarios: stale context, task done, clear sensitive data. Suggests pairing with remember and recall, but does not give exclusions or explicit 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 indicate read-only, idempotent, and non-destructive behavior. The description adds valuable details: fetches the page, extracts content, emits standard markdown, and notes it's for AI crawlers. No contradictions, and the added context is appropriate.

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

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

Three sentences: purpose, process, use cases. No wasted words, efficient and well-structured. Each sentence adds distinct value.

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

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

For a two-parameter tool without output schema, the description adequately explains the output (single text blob) and covers main use cases. It does not detail error handling or edge cases, but given simplicity and annotations, 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% (both params described). The description adds real-world examples for 'url' (e.g., 'https://example.com') and implies 'max_links' controls link count. This supplements the schema without redundancy.

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

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

The description clearly states the tool generates an llms.txt file for any URL, specifying the process (fetch, extract title/description/links) and output format. It distinguishes itself from sibling tools by focusing on a unique output (llms.txt), not offered by any listed sibling.

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 use cases (indexing client sites, drafting for own project, auditing competitors), giving clear context for when to use. It lacks explicit when-not-to-use or alternative tool names, but the specificity is sufficient for an AI agent.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint=false. Description adds that it returns caller's subscriptions and fields, but doesn't contradict annotations.

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

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

Two sentences, front-loaded with main purpose, includes return fields and usage guidance. No wasted words.

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

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

No output schema, but description lists key return fields. Combined with schema and annotations, it provides sufficient context for a simple list tool.

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

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

Schema coverage is 100% for the single parameter 'include_inactive'. Description implies default false ('active') but adds 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?

Description uses specific verb 'list' and resource 'subscriptions', states it returns specific fields (id, type, params, etc.), and is clearly distinguishable from sibling tools like subscribe/unsubscribe.

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

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

Explicitly states when to use: 'review what you're monitoring before adding more or to find an id to cancel', providing clear context and 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 are uninformative (all false), so the description carries the burden. It richly discloses behavior: filing without an account returns a claim_token, passing it back later reads status, rate limits (5 per identifier per day), free, and how the team processes feedback ('reads digests daily'). No contradiction with annotations.

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

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

The description is longer than average but every sentence serves a purpose: purpose, usage, exclusions, token flow, rate limits, and cost. It is front-loaded with the main action and well organized, making it efficient despite the 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?

Given 4 parameters (one nested), no output schema, and no helpful annotations, the description is remarkably complete. It explains the return token semantics, rate limiting, scope, and how to frame feedback, covering all critical operational context an agent needs to invoke this tool correctly.

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

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

Schema already describes all parameters, but the description adds significant semantic value: it explains the claim_token flow ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), clarifies message guidance ('Be specific... 1-2 sentences typical, 2000 chars max'), and instructs not to paste end-user prompts. This goes well beyond the 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 opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from siblings by focusing on feedback submission rather than research or ticket operations, and also identifies the tool's scope (Pipeworx tools only).

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

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

The description explicitly states when to use the tool ('Use when a tool returns wrong/stale data... etc.') and when not to ('ONLY for tools served by this Pipeworx connection... file it with that server instead'). It also gives a concrete rule for disambiguation: 'Pipeworx tool names are the ones this connection lists.'

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral details: caching (5min-1h), data source (CF analytics-engine), no PII, and the exact output structure (pack, tool, count). 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: starts with the core purpose, lists use cases, then provides technical details. Every sentence adds value. No fluff. Length is appropriate for the tool's complexity.

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

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

Given no output schema, the description sufficiently explains the return shape (top tools, top packs, total call volume). It covers caching, data source, privacy, and window semantics. For a simple tool with one optional parameter, this is fully 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 a description for the 'window' parameter. The description adds strategic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides meaning beyond the enum values and schema description.

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

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

The description clearly states what the tool does: returns top tools, top packs, and total call volume over recent windows. It uses specific verbs like 'returns' and specifies the resource (trending data on Pipeworx). The description distinguishes it from siblings like 'discover_tools' by focusing on aggregated trending signals rather than listing all tools.

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

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

The description explicitly lists three concrete use cases (discovering hot data sources, confirming a popular tool, aligning use case with needs). It provides context on when to use shorter vs longer windows. However, it does not explicitly state when NOT to use this tool or mention 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral detail: methodology (monotonicity, partition-check), partition filter (placeholder slugs), fill check (live CLOB depth, realizable_edge_pp), and warnings not to trade when realizable_edge_pp <= 0. 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 mode separation, but it is verbose. Each sentence adds value, yet some details like the fill check could be streamlined. Front-loading the main purpose is good, but overall length could be reduced while maintaining clarity.

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

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

Given the tool's complexity (multiple modes, partition checks, fill analysis, output structure) and lack of output schema, the description is remarkably complete. It details return fields (opportunities[], gap_pp, suggested_trade, etc.), behavioral constraints (Jaccard threshold, placeholder filter), and even references a sibling tool for custom sizing (polymarket_fill_risk).

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 brief parameter descriptions (event slug, topic string). The description significantly enriches both parameters: for event it explains the internal checks (date-axis/threshold-axis ordering, partition_check), for topic it explains cross-event scanning and Jaccard similarity threshold. Provides far more meaning than 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 immediately states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies three distinct modes (no args, event, topic) with clear purpose for each, distinguishing them effectively.

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

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

The description provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. However, it does not compare this tool to sibling tools like polymarket_edges or polymarket_fill_risk, missing an opportunity to clarify when not to use this tool.

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

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

The description goes far beyond annotations by detailing three model families, caching behavior (1h KV-level), response structure with diagnostics, and warnings like the 24h-move indicator. It fully discloses how edges are computed, tradeable-edge knobs, and limitations (e.g., Fed signal unreliability). 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 lengthy but front-loaded with the main purpose and then efficiently covers model families, knobs, and response structure. Every sentence earns its place for a complex tool; minor trimming could be done, but it's not excessive.

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

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

Given 9 parameters and no output schema, the description is exceptionally complete. It explains the three segments, edge metrics, response fields, diagnostics, and caching. It leaves no major gaps about what the tool returns or how to interpret results.

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

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

All 9 parameters have schema descriptions (100% coverage), so the baseline is high. The description adds significant context beyond the schema, such as explaining that min_kelly does not filter partition arbs and describing how min_partition_leg_kelly works at the per-leg level. This adds meaningful guidance.

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

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

The description starts with a clear verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also states the use case: 'Built for "what should I bet on today"' and distinguishes it from siblings like polymarket_arbitrage by focusing on Pipeworx disagreement.

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 this tool ('agents discover opportunities without paging hundreds of markets') and provides context on when not to use (e.g., Fed bets excluded from ranking). However, it does not explicitly contrast with alternatives or state exclusions like 'use this instead of X when Y'.

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, destructiveHint, idempotentHint, openWorldHint. Description adds significant behavioral detail: response structure (tracked, expired, snapshot_dates), meaning of negative values, decay computation, and limitations (60-day TTL, snapshot start). No contradiction with annotations.

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

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

Description is relatively long and dense, mixing tool purpose with detailed response structure. While informative, it could be more concise by separating overview from response details.

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

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

Despite having no output schema, description thoroughly explains response fields (tracked with time-series and trend, expired with lifespan, snapshot dates) and tool limitations. Provides sufficient context for an agent to correctly interpret results.

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

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

Schema description coverage is 100% with clear descriptions for both parameters. Description repeats the same information without adding new semantic depth beyond restating defaults and options. Baseline score of 3 is appropriate.

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

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

Description clearly states the tool tracks edge persistence and decay using daily snapshots, answering how long an edge has existed and if it's shrinking. It distinguishes from sibling tools like polymarket_edges by focusing on historical trends and decay computation.

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

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

Provides context on when to use (to understand edge history and decay). Does not explicitly state when not to use or name alternatives, but the description implies differentiation from the current-edge snapshot tool.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds behavioral details beyond annotations: it walks the order-book ladder, returns specific fields (e.g., top_of_book, vwap_fill_price, slippage_pp), and warns about partial basket fills converting an arb into an unhedged directional position. This provides valuable transparency about the tool's effects and limitations.

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

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

The description is relatively long but efficiently structured: it starts with the core purpose, then explains two modes with bullet-like detail, and ends with usage guidance. All sentences add necessary information; however, the dense text could be slightly more scannable with explicit bullet points for return fields. Still, it is concise for the complexity covered.

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

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

Given the tool's complexity (two modes, multiple return fields) and the absence of an output schema, the description provides detailed information about the output structure and behavioral nuances (e.g., thin_legs, forced_directional_risk). It explains the purpose of the risk check and the consequences of partial fills. This is sufficient for an AI agent to understand when and how to use the tool.

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

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

Schema description coverage is 100%, but the description adds significant operational semantics: it explains how 'size_usd' is interpreted differently in single-market vs basket mode, and clarifies the default behavior for 'side' in basket mode (auto from partition sum). This goes beyond the schema's parameter descriptions and helps the agent understand parameter interplay.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes itself from sibling tools (polymarket_arbitrage, polymarket_edges) by specifying when to use it: before acting on those signals or for trades above ~$500. It also outlines two modes (single-market and basket) with specific verbs and 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 explicitly states when to use the tool ('USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and explains the two modes requiring either 'market' or 'event'. It provides clear context but does not explicitly state when not to use it, which would strengthen clarity further.

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

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

The description adds substantial behavioral context beyond the annotations (readOnly, idempotent, non-destructive). It explains compatibility warnings, temporal alignment fields, and skipped cross types in detail, providing complete transparency about edge cases and data quality.

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

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

The description is relatively long but is well-structured with clearly labeled sections (modes, response, safety fields). It front-loads the purpose and each sentence adds information. Minor redundancy could be trimmed.

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, no output schema, and three optional parameters, the description thoroughly covers response fields, safety checks, temporal alignment, and compatibility warnings. It is complete enough for an AI agent to understand 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?

With 100% schema coverage, the description still adds value by explaining the interplay between 'topic' and explicit parameters, the two modes, and the relationships among them. It goes beyond the schema descriptions.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It uses specific verbs and resources, and distinguishes itself from sibling tools like 'polymarket_arbitrage' by focusing on this specific pair.

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 two modes (topic vs explicit tickers) and explains that pre-mapped topics often yield compatibility warnings, setting appropriate expectations. However, it does not explicitly contrast with alternatives like 'polymarket_arbitrage' or state when NOT to use this tool.

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

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

Annotations declare read-only, idempotent, non-destructive. The description adds scoping details (anonymous IP, BYO key hash, account ID) and the behavior of omitting key to list all keys, which 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?

Two sentences, front-loaded with purpose, no wasted words. Every sentence adds value.

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

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

For a simple tool with 1 param and no output schema, the description covers purpose, usage, behavior, and scoping completely. No gaps.

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

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

Schema coverage is 100% with the key parameter described. The description reinforces omitting key to list all keys, adding context beyond the schema. No param details are missing.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys, with a specific verb (retrieve/list) and resource (saved values/keys). It distinguishes from siblings remember and forget.

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

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

The description advises when to use it (look up stored context) and provides examples, but does not explicitly state when not to use it. It mentions pairing with remember and forget, but no explicit 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral details: explains the mark_read effect ('flag returned events read so the next call only shows newer ones'), describes event structure (source, citation_uri, raw payload), and notes the limit range (1-200, default 50). 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 compact: 3 sentences front-loaded with the purpose, followed by parameter details and an alternative endpoint. 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?

No output schema exists, so the description must cover return values. It does: each event carries source, citation_uri, and raw payload. It also covers pagination (limit) and read-state management. Lacks discussion of empty results or error cases, but is sufficient for a straightforward read tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema: provides an example for type ('sec_8k'), clarifies that since expects an ISO timestamp, and explains mark_read and unread_only semantics. This elevates it above baseline.

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

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

The description opens with a clear verb+resource: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed alerts) and distinguishes from sibling tools like list_subscriptions and subscribe, which manage subscriptions rather than retrieve recent 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 mentions that 'Polls work fine' and provides an HTTP alternative for scripts/dashboards, giving explicit when-to-use guidance. However, it does not explicitly exclude alternatives like search_within or compare_entities for deeper querying, though the context is clear enough.

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

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

Discloses multi-source fan-out (SEC EDGAR, GDELT→GNews fallback, USPTO), handling of rate limits/errors, and the USPTO PatentsView API sunset. Also describes return structure (changes[] grouped by source, total_changes count, citation URIs). No contradiction with annotations.

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

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

Description is well-structured with front-loaded examples, clear explanations, and no wasted words. Every sentence serves a 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?

Describes return structure despite no output schema. Covers source details, failure modes, and typical usage patterns. Complete for a tool of this complexity.

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

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

All three parameters are described with additional context beyond the schema: type constrained to 'company', since with examples and common usage, value explaining ticker or CIK. Schema coverage is 100%, and description adds meaningful guidance.

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

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

Description clearly states the tool provides a change feed for a company in a specified window. Uses colloquial examples like "What's new with X" and explicitly distinguishes from sibling tool 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?

Provides explicit guidance on when to use this tool vs entity_profile. Includes examples of acceptable since values (ISO date and relative shorthand) and typical monitoring recommendation ("30d" or "1m").

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds context about scoping by identifier and persistence duration (24 hours for anonymous), but could more explicitly state that repeated writes with the same key overwrite the value.

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

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

The description is concise with three sentences, front-loading the core purpose, followed by usage context and technical details. 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 and absence of an output schema, the description covers purpose, parameters, usage, and behavioral traits completely. It also references sibling tools directly.

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 describes both parameters with 100% coverage. The description adds value by providing examples for key (e.g., 'subject_property') and clarifying value as any text, as well as mentioning scope by identifier, which is not in the schema.

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

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

The description explicitly states the verb 'save' and the resource 'data', and distinguishes itself from siblings like recall and forget. It clearly defines the tool's purpose as storing data for reuse across conversations or sessions.

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

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

The description provides explicit guidance on when to use the tool ('when you discover something worth carrying forward'), pairs it with recall and forget for retrieval and deletion, and explains scoping and persistence differences for authenticated vs. anonymous users.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds valuable behavioral context: graceful degradation of LEI/FIGI enrichment, explicit reporting of unresolved identifiers, internal cascading lookups, and ISIN-to-LEI mapping behavior. No contradiction with annotations.

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

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

The description is very long and dense, with some redundancy (e.g., multiple examples and the 'Use FIRST' instruction alongside 'replaces 2-3 manual lookups'). It is front-loaded with concrete examples and clear purpose, but would benefit from tighter formatting.

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 thoroughly explains what is returned for both company and drug types, including sources, ownership context, unresolved identifiers, and failure behavior. It fully covers the complexity of this multi-endpoint resolver.

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 extra meaning beyond schema: it reveals that company value also accepts ISIN (not mentioned in schema) and explains what each type returns (e.g., RxCUI, LEI, FIGI). This is substantial added semantic 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 resolves user-spoken names to canonical/official identifiers needed by other tools, with explicit supported types (company, drug). The examples and 'Use FIRST whenever you have a name but need an ID' strongly distinguish it from sibling tools like entity_profile 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?

The description gives clear usage context ('Use FIRST whenever you have a name but need an ID') and elaborates on input forms per type. It does not explicitly name alternative tools or exclusion cases, but the 'FIRST' directive strongly implies precedence over 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 mark as read-only and idempotent. Description adds key behavioral details: probes each entity with ai_visibility_check, ranks by score, returns score/confidence/signal density. No contradictions.

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

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

Two concise sentences plus a parenthetical example. Front-loaded with main purpose, no redundant fillers. Every sentence contributes.

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

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

Given no output schema, description adequately explains return format (ranked list with score, confidence, signal density). Also specifies input constraints (2-8 entities). Sufficient for complex multi-probe tool.

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

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

Schema covers all 4 parameters (100% coverage). Description adds semantic value: explains 'entities' array (first entry as subject, rest as competitors) and purpose of 'context' parameter for disambiguation.

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 'Compare AI visibility across multiple entities side-by-side' with specific verb (compare), resource (AI visibility), and scope (multiple entities). Distinguishes from sibling 'ai_visibility_check' by mentioning probing with that tool and ranking 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?

Provides clear usage context: 'useful for competitive AI-marketing audits' with an example question. Implies single-entity checks should use the sibling tool, but does not explicitly state exclusions or alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds that it fans out across services, partially fails gracefully, and that bundlephobia first measurement can take 5-30s and will be listed in sources_failed on timeout.

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, well-structured paragraph. Front-loaded with the composite nature and immediate purpose. Every sentence adds necessary detail 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?

Despite no output schema, the description enumerates return fields (summary block, advisories, links, alternative versions) and explains partial failure behavior. Adequately covers the tool's functionality for an AI agent.

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

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

Schema has 100% coverage with descriptions for both parameters. Description adds that scoped packages are accepted for 'package' and that 'version' defaults to latest, providing additional 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?

Clearly states the tool is a composite check for npm packages combining deps.dev and bundlephobia data. The verb 'scan' and resource 'dependency' are precise, and the description distinguishes it from sibling tools by specifying its purpose and ecosystem.

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 about safety, popularity, or cost of an npm package. Provides exclusions (NPM only in v1, other ecosystems handled elsewhere) and mentions graceful degradation with timing caveats.

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, describes return format (passages with character offsets and similarity scores), embedding model (BGE-base-en), windowing (500-char overlapping), and limit (200K chars with truncation flag). No contradiction with annotations.

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

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

Concise yet comprehensive. Four sentences cover purpose, usage, return values, and technical details. 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?

Fully explains inputs and outputs despite no output schema. Covers truncation behavior and embedding details. All relevant context for agent to invoke correctly.

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

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

Schema coverage is 100% so baseline 3. Description adds context: text should be a fetched record, query is natural-language, and limit controls number of passages. 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?

Clear verb (semantic search) and resource (inside a fetched record). Distinguishes from sibling ask_pipeworx_grounded by describing how they pair together.

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

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

Explicit when-to-use: when record is too large for prompt. Mentions pairing with ask_pipeworx_grounded for grounding, giving clear alternative strategy.

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 (readOnlyHint=false, destructiveHint=false, idempotentHint=true) are consistent. Description adds behavioral details: returns subscription id, requires OAuth, delivery constraints, and type-specific parameters. No contradictions.

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

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

Description is well-structured and front-loaded with purpose, but somewhat lengthy. Every sentence adds value, though minor redundancy exists (e.g., delivery details repeated in schema description and text). Good overall.

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

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

Covers all essential aspects: purpose, preconditions, type options, parameter details, delivery channels, return value, and limitations. No output schema, but return value is clearly stated. Complete for an agent to use.

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

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

Schema coverage is 100%, but description significantly expands on parameter meaning with concrete examples for each type, detailed delivery channel constraints, and required/optional fields. Adds substantial value beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns the new subscription id, with specific supported types and delivery channels. Differentiated from siblings like list_subscriptions and unsubscribe.

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

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

Specifies prerequisite (Pipeworx OAuth account) and delivery limitations (phone verification, 10/day cap). Does not explicitly mention when not to use, but context is sufficient for selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds value by explaining that it returns example questions with tool+argument shape, but behavioral traits are well-covered by annotations.

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

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

The description is fairly long but well-structured with clear separation of purpose and details. Every sentence adds value, though it could be slightly more concise.

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

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

Given the tool is simple (1 optional param, no output schema), the description is complete: it explains return format, categories, and usage context.

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

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

Schema description coverage is 100%. The description further explains the topic parameter's possible values and behavior when omitted, adding meaning beyond the schema.

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

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

The description states 'returns category-bucketed example questions' with specific verb+resource. It distinguishes from siblings by being the onboarding entry point for Pipeworx.

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

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

Explicitly says to use this FIRST when you do not know what Pipeworx can do, and mentions when to omit or pass a topic. Provides clear context on when to use vs alternatives like ask_pipeworx.

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

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

Beyond the annotations (which include idempotentHint=true, destructiveHint=false, etc.), the description adds key behavioral details: ownership enforcement, deactivation instead of deletion, and preservation of historical events. 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?

Three sentences: first states the action, second explains ownership constraint, third clarifies behavioral effect. No wasted words, key points front-loaded.

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

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

The description adequately covers behavior and constraints for a simple idempotent tool with one parameter. While it lacks explicit mention of return value or confirmation, the behavioral effects are well described. Missing output schema means the description must stand alone, which it does reasonably well.

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

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

The id parameter is fully documented in the schema with a description referencing the subscribe tool. The tool description adds no new parameter information beyond what the schema provides. With 100% coverage, baseline 3 is appropriate.

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

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

The description clearly states it cancels a subscription by id, using a specific verb 'Cancel' and specific resource 'subscription'. This clearly distinguishes it from sibling tools like subscribe and list_subscriptions.

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

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

The description mentions ownership enforcement and the effect of deactivation, giving clear context on when it's appropriate. However, it does not explicitly state when not to use it or name alternative tools for edge cases.

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

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

Annotations already mark it read-only and open-world, but description adds crucial behavioral nuance: could_not_verify means the check didn't happen and shouldn't be treated as evidence, unsupported means no source coverage. Also clarifies the fast-path vs grounded pipeline. 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?

Despite being longer than typical, every sentence earns its place. Starts with usage intents and purpose, then details routing, return values, and an essential warning about could_not_verify. Well-structured and front-loaded; no fluff.

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

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

With no output schema, the description thoroughly explains the verdict types, actual value with citation, reasoning, and error semantics. It covers edge cases and usage context, making it complete for a complex tool with two pipelines.

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 100% of both parameters with detailed descriptions. The tool description adds context about percent-delta math for financial claims but doesn't elaborate on tolerance_pct beyond schema. Baseline 3 is appropriate since schema carries the burden.

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

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

Description clearly states the tool performs natural-language claim verification against authoritative sources, with specific verb 'verify' and resource 'claims'. It provides concrete user intents and distinguishes itself from siblings by focusing solely on fact-checking, even noting it replaces 4-6 sequential calls.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes two routing paths (SEC EDGAR for company-financial, grounded pipeline for other facts) and implies not to compose multiple calls. Clear context for when to use this over alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds no extra behavioral context (e.g., error handling, authentication). 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?

Single sentence, zero wasted words. Perfectly concise for a simple get-by-ID operation.

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

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

For a simple retrieval tool with a single parameter and an output schema, the description is adequate. It doesn't cover edge cases (e.g., non-existent ticket), but the output schema likely handles 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 covers parameter 'id' with description 'Ticket ID'. Description does not add additional meaning beyond the schema, which has 100% coverage.

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

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

Description 'Get a Zendesk ticket by ID' uses a specific verb and resource, clearly distinguishing it from sibling tools like zd_list_tickets and zd_search_tickets.

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

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

No explicit guidance on when to use this tool versus alternatives (e.g., when to use zd_search_tickets instead). Usage must be inferred from the name and schema.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds no additional behavioral context (e.g., error cases, permission requirements). It neither contradicts nor enriches 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 a single, complete sentence. It is concise, front-loaded, and has no unnecessary words. Every word earns its place.

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

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

Given the tool's simplicity (one parameter, no nested objects, output schema exists), the description is mostly complete. However, it could mention that the user is returned in the response, but since an output schema is present, this is not strictly necessary.

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

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

The input schema has 100% coverage, describing the 'id' parameter as 'User ID'. The description adds no further meaning beyond what the schema already provides, so baseline score 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 is specific: 'Get a Zendesk user by ID.' It clearly states the verb (Get), resource (Zendesk user), and scope (by ID). This distinguishes it from sibling tools like zd_list_users (list all users) and zd_search_tickets (search tickets).

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

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

The description gives no explicit guidance on when to use this tool versus alternatives. Usage is implied: use when you have a specific user ID and need a single user. No exclusions or alternative tools are mentioned.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds value by specifying sortability, return fields (IDs, subjects, statuses, metadata), and pagination support via 'page'. 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 two concise sentences, with the primary action stated first. Every sentence adds value without redundancy or unnecessary 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?

Given the presence of an output schema, the description adequately covers functionality (listing, sorting, pagination). It does not mention default sorting or scope limits, but these are minor given the output schema's expected role.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the sortable fields and pagination, but does not add new meaning beyond the schema definitions. No additional parameter constraints or formats are explained.

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

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

The description clearly states that the tool lists Zendesk support tickets for the connected account, with explicit mention of sorting options and return fields. This distinguishes it from sibling tools like zd_get_ticket (single ticket retrieval) and zd_search_tickets (search-based filtering).

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?

While the description implies a general listing use case, it does not explicitly guide when to use this tool versus the sibling zd_search_tickets for filtered searches. The guidance is adequate but could be improved by contrasting with search capabilities.

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

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

Adds value beyond annotations by specifying return fields (IDs, names, emails, roles) and pagination support. Annotations already cover safety, and description complements them without contradiction.

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

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

Two sentences with no wasted words. First sentence states purpose, second details return and pagination. Front-loaded and efficient.

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

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

Covers essential aspects: scope, return fields, pagination. Could mention default page or limits, but with output schema present and annotations rich, 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 has 100% coverage with 'Page number'. Description adds context that page is for pagination, linking it to the listing behavior, which is useful for agent understanding.

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

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

Clearly states the verb 'List' and resource 'Zendesk users', specifying scope as all agents and end-users. Distinguishes from siblings like zd_get_user (single user) and zd_search_tickets (tickets).

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?

Implicitly indicates use for listing all users, but does not explicitly exclude alternatives or provide when-not-to-use guidance. The sibling context provides some differentiation.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which cover safety and idempotency. The description adds no additional behavioral context such as rate limits, pagination, or result format. With annotations present, the description is adequate but not enriched.

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

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

The description is a single, concise sentence that is front-loaded with the key action and resource. No superfluous words or 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?

The description is minimal but sufficient given the simple tool (one parameter, annotations, output schema exists). However, it lacks mention of the return format or that it uses Zendesk's search API, which would help an agent anticipate results. Adequate but not enriched.

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

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

The input schema covers 100% of the parameter with a clear description and examples. The tool description merely restates 'with a query string', adding no new semantic value beyond what the schema already provides. Baseline of 3 is appropriate.

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

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

The description clearly states the verb 'Search', the resource 'Zendesk tickets', and the method 'with a query string'. It effectively distinguishes from siblings like zd_list_tickets (listing without search) and zd_get_ticket (single ticket 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 does not provide explicit guidance on when to use this tool versus alternatives like zd_list_tickets or zd_get_ticket. The context is implied but not stated, and no when-not or exclusion conditions are mentioned.

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