Zoom

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds important behavioral details such as the default free model, the need for a BYO API key for Anthropic, and the return structure. It does not mention rate limits or error handling, but given annotation coverage, this is sufficient.

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

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

The description is concise, with two focused sentences covering action, defaults, optional features, and return format, plus a clear use-case sentence. Every word adds value, and the front-loaded structure aids quick understanding.

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

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

Despite lacking an output schema, the description thoroughly explains the return structure (per-model score, confidence, signals, raw_response, combined view). Given the moderate complexity (4 params, no enums), the description is complete enough for effective 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?

All 4 parameters are well-described in the schema (100% coverage). The description adds value beyond the schema by explaining the default model, the purpose of the API key, and how the context parameter disambiguates entities. This is excellent guidance for an AI agent.

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

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

The description clearly states the tool's purpose: to probe LLMs for knowledge about a brand or topic and output a visibility score. It specifies the default model and optional Anthropic probe, distinguishing it from sibling tools like scan_competitor_ai_presence which is more focused on competitors.

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 it is useful for AI-marketing audits, pre-launch checks, and competitive monitoring, providing context. However, it does not explicitly state when not to use it or directly compare to siblings, missing a small opportunity for clearer guidance.

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

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

The annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds useful behavioral context beyond that: it routes the question to the correct source tool, fills in arguments automatically, and returns structured answers with pipeworx:// citation URIs. This helps the agent predict the interaction model even without an output schema.

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

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

The description is longer than average but front-loads the most important directive and supports it with concrete examples and sibling-tool boundaries. It earns its length for a router tool of this scope, though a few phrases are somewhat redundant and could be tightened.

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

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

Given the tool's broad routing behavior, one required parameter, and complete annotation coverage, the description gives agents enough context to decide correctly and invoke it. It explains the domain coverage, the output shape and citation behavior, representative examples, and alternative tools for narrower or broader research needs.

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

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

The input schema already documents the single required question parameter and its aliases at 100% coverage. The description reinforces natural-language usage but does not add meaning beyond the schema. Baseline 3 is appropriate because schema coverage is complete and the description does not complicate 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?

The description clearly identifies ask_pipeworx as a natural-language router that answers authoritative factual questions by selecting one of thousands of verified source tools and returning structured answers with citations. It uses concrete verbs and examples, and names how it differs from sibling tools like ask_pipeworx_grounded and deep_research.

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

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

The description explicitly says to prefer this tool over web search for current or historical factual questions, lists common question phrasings such as 'what is' and 'get the latest', and provides examples. It also states when to choose ask_pipeworx_grounded for verbatim-evidence answers and deep_research for broad multi-part questions, so the agent gets both inclusion and exclusion guidance.

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

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

Annotations already declare the tool as read-only, idempotent, non-destructive, and open-world, so the description correctly avoids repeating those facts. It adds meaningful behavioral context: beta status, enabling of candidate routing improvements live, the exact state of no active candidate, the retirement date, and the fact that it does not fall back to another tool. This is the kind of context annotations cannot convey.

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 purpose and provides useful state, usage, and behavioral context. It is slightly longer than necessary because the idea 'same as ask_pipeworx' is restated multiple times, but every sentence adds a distinct piece of context such as current candidate status or fallback behavior.

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 tool has one required parameter, no output schema, and annotations that cover safety. The description adequately supplies the missing response shape by reference to ask_pipeworx, discloses current beta state, and explains exact expected usage. However, it depends on the agent already knowing ask_pipeworx's response shape for full understanding, so it is not perfectly self-contained.

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 `question` parameter and five aliases clearly documented. The description only confirms that arguments match ask_pipeworx, which is useful but not necessary to understand the individual parameters. The schema carries the parameter burden here, so a baseline score of 3 is appropriate.

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

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

The description identifies the tool as a beta version of ask_pipeworx, explicitly calling it a universal router with the same 5,621 tools, arguments, and response shape. It clearly differentiates itself from the stable ask_pipeworx and from ask_pipeworx_grounded. The 'full working router' clarification removes any ambiguity about whether it is a wrapper or fallback.

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

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

The description explicitly says to use it like ask_pipeworx when you want the newest routing, and notes that results are compared against the stable router. It names the stable alternative and the experimental context, but it does not explicitly state a when-not-to-use case, such as 'use ask_pipeworx when you need stable behavior only'.

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 openWorldHint=true, but the description adds substantial context beyond them: the exact return shape {answer, evidence, confidence, source, fetched_at, refusal_reason:null}, the full enumerated refusal_reason values (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), the refusal-when-not-directly-answered policy, and the cost of one extra LLM call. This is exactly disclosure that annotations cannot express.

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?

It is unapologetically dense and long, but every clause earns its place: mechanism, return contract, refusal reasons, use cases, and cost trade-off all present. The core purpose is front-loaded in the first sentence. A small trim of repeated wording (e.g., 'the data doesn't directly answer' restating refusal semantics) could tighten it, but no filler is present.

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

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

Despite having no output schema, the description fully specifies the success return object and each refusal_reason value, covers routing behavior ('picks the right tool from 5,621 across 1472 sources, fills arguments'), states the extra LLM-call cost, and gives verbatim-typed use cases. An agent can summon it correctly and interpret its result without any other documentation. Nothing needed to call it safely is missing.

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

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

Schema coverage is 100% — all six parameters (question, q, query, prompt, text, input) are explicitly documented as aliases for the natural-language question, and the main 'question' param has a full description. The description adds no parameter-level meaning beyond saying the question is routed to source selection, which is not needed given the schema already covers all params. 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 opens with 'Hallucination-resistant answer mode for high-stakes asks,' which is a specific verb plus resource plus a distinctive behavioral scope. It differentiates itself from ask_pipeworx by explaining its extraction-only mechanism ('then EXTRACTS the answer using ONLY what the tool result contains') and its explicit refusal contract, which no sibling description could be confused with.

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?

Usage guidance is explicit and decision-oriented: 'Use whenever an answer will be quoted, cited, or acted on... (financial verdicts, legal claims, medical lookups, public statements)' and the exclusion 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' It names the exact alternative and gives a cost-based criterion for choosing between them — nothing is left to inference.

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

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

Annotations already mark readOnlyHint and idempotentHint, but the description adds extensive behavioral details: low-confidence resolution short-circuiting, closed market handling, wide-spread tradeability warnings, resolution-rule risk parsing, and fallback behavior in news fetching. No contradictions with annotations.

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

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

The description is very long and dense, packing detailed behavioral notes, fan-out examples, and edge cases into a single paragraph. While well-organized, it could be more concise; some details like the note on de-indexed markets are secondary. It front-loads the core purpose.

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

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

Given no output schema and high complexity (multiple classifiers, error states, response shapes), the description covers all critical aspects: resolution confidence, parent events, news fallback, cancellation rules, and tradeability. It is exhaustive for the tool's scope.

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

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

Schema coverage is 100% and the description enriches each parameter: market can be slug, URL, or text; depth explains quick vs thorough; include_raw clarifies default false and when to use true. This adds meaningful context beyond the schema's minimal 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 researches a Polymarket bet by pulling Pipeworx data in one call. It specifies the inputs (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison). It distinguishes from related sibling tools like polymarket_arbitrage and polymarket_edges by focusing on holistic 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?

The description explicitly states use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. This gives clear context for when to invoke this tool. It does not explicitly exclude cases or compare to alternatives, but the usage guidance is specific enough for typical queries.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds significant behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), specific metrics returned (revenue, net income, cash, debt; adverse-event counts, approval counts, trial counts), off-calendar fiscal year handling, result sorting by primary metric, and citation URI inclusion. 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 a single focused paragraph with no wasted words. It front-loads user-facing phrases, then explains functionality, data sources, sorting, and output. Every sentence contributes meaning.

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

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

Given the tool's complexity (two entity types, multiple data sources, no output schema), the description adequately covers inputs, data sources, sorting, and output format (paired data + citation URIs). It mentions off-calendar handling for companies. Could mention that output is structured (e.g., table or JSON), but overall very complete 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 coverage is 100% with descriptions for both parameters (type enum, values array). Description adds value by explaining data sources per type and off-calendar fiscal year handling, but the core parameter meanings are already clear from schema. The additional context about sorting and output format 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?

Description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one call, with specific verb phrases like 'compare X and Y' and 'X vs Y'. It distinguishes from sibling tools by explicitly advocating preference over sequential single-pack lookups (e.g., 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?

Description provides clear when-to-use guidance: when comparing entities, with example queries. It explicitly advises to ALWAYS PREFER this tool over sequential single-pack lookups, effectively identifying the alternative (entity_profile). No unnecessary exclusions needed.

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

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

The annotations already signal readOnly, openWorld, and idempotent behavior. The description goes well beyond that by explaining parallel decomposition across 5,621 tools, gaps[] (never invented), contradictions[], hop fields, citation_uri fetchability, semantic excerpting, and expected latency ranges. Highly transparent and 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?

Dense and information-rich, but coherently front-loaded with the account caveat and core constraint. Every sentence adds value; the only minor flaw is that it reads as one running block, which slightly reduces scannability. Still appropriate for a comprehensive tool.

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

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

For a tool with no output schema, the description fully covers return format (findings packet: evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]), behavioral semantics, prerequisites, sibling routing, latency, and depth tiers. Nothing an agent needs to select correctly is left out.

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 already comprehensive at 100%, so a baseline of 3 is warranted. The description adds value above the schema by clarifying quick/standard/thorough in behavioral terms (single hop vs gap recovery vs lead chasing), which helps an agent choose meaningfully. Slight deduction for not adding new detail to the question parameter beyond the schema.

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

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

The description explicitly states the tool's core purpose: grounded multi-source research across Pipeworx's structured data sources in one call. It calls out what it is NOT (open-web search), names concrete example use cases, and distinguishes itself from ask_pipeworx and ask_pipeworx (sibling differentiation).

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

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

It gives explicit when-to-use and when-not-to-use guidance: use ask_pipeworx instead if not signed in; prefer ask_pipeworx for a single lookup or for breaking news; use deep_research for broad/multi-part questions over structured data. It also clarifies depth-tier tradeoffs (standard vs thorough).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it returns top-N most relevant tools with full schemas and curated examples, and results are 'ready to call directly.' This explains the non-destructive, idempotent, and read-only nature, and adds detail about the output format.

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 efficient and front-loaded with the core purpose: 'Find tools by describing the data or task.' Each subsequent sentence adds meaningful detail without redundancy. It is appropriately sized for the tool's simplicity.

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

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

Given the tool's role as a dispatcher with 6 parameters and no output schema, the description covers its purpose, input format, return content (names, descriptions, schemas, examples), and when to use it. It could mention how relevance is determined, but that is not critical. The description is sufficiently complete for an AI agent to use the tool correctly.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description adds minimal additional semantics beyond stating the tool accepts a natural language query and listing domains. It also clarifies the 'limit' parameter by stating it returns 'top-N most relevant tools.' This justifies a baseline 3.

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

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

The description clearly states 'Find tools by describing the data or task,' which is a specific verb and resource. It enumerates many domains and distinguishes this tool from its siblings (which are specific data/task tools) by positioning it as a discovery meta-tool. This makes the tool's purpose unmistakable.

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

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

The description explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear when-to-use guidance. It does not explicitly state when not to use, but the context strongly implies it's for exploration rather than direct querying.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral context beyond annotations: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), notes the USPTO patents component will sunset May 2025 with soft-fail behavior, and describes return structure. No contradiction.

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

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

The description is relatively long but efficiently packed with essential information. Front-loads query examples for quick recognition. Every sentence serves a purpose (usage guidance, return structure, limitations). Minor reduction in length possible, but 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?

Despite no output schema, the description provides a thorough overview of return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). Limitations (patents sunset, names unsupported) are clearly stated. For a complex tool aggregating multiple data sources, this is complete and sets correct expectations.

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

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

Schema coverage is 100% with descriptions for both 'type' and 'value'. The description adds significant meaning beyond the schema: explains value can be ticker or zero-padded CIK, explicitly states names are unsupported, and clarifies type enum is limited to 'company' for now. This extra context helps the agent pass correct 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 starts with concrete query examples ('Tell me about X', 'research Acme') and clearly states the tool returns a full cross-source profile of a US public company in one parallel call. It explicitly distinguishes from siblings like deep_research and compare_entities by advocating preference over chaining single-source lookups.

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

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

The description provides explicit when-to-use guidance ('ALWAYS PREFER over chaining... when the user asks for a holistic view') and when-not-to-use ('names not supported – use resolve_entity first if you only have a name'). This leaves no ambiguity about appropriate invocation 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 destructiveHint=true and idempotentHint=true. The description adds minimal behavioral context beyond the fact of deletion; it does not detail error handling or side effects.

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

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

Two efficient sentences. The first states the action clearly, the second provides usage context and sibling references. No wasted words.

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

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

For a simple tool with full annotation coverage and one parameter, the description is complete: it explains the action, when to use, and relationship to sibling tools.

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

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

With 100% schema description coverage, the schema already defines the 'key' parameter. The description adds no new parameter semantics beyond mentioning 'by key'.

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 'Delete a previously stored memory by key' and distinguishes itself from siblings like 'remember' and 'recall'.

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

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

The description provides explicit guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier. Pair with remember and recall.'

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description confirms the fetch-and-extract behavior but adds minimal extra context beyond 'production-ready' and the output location. No contradictions.

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

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

Single, well-structured paragraph that front-loads the action and expands with 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?

With only two parameters and no output schema, the description fully covers the tool's behavior, output format, and usage context. No gaps remain.

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

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

Schema description coverage is 100%; the description repeats what the schema's descriptions already state (e.g., 'Full URL', 'Maximum number of link entries'). No 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 it generates a production-ready llms.txt file for any URL, specifies the output format and target crawlers, and provides concrete use cases that differentiate it from sibling tools like 'scan_competitor_ai_presence'.

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

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

Lists specific use cases (client site indexing, personal project drafting, competitor auditing) but does not explicitly state when not to use or compare to alternatives. The context is sufficient for an agent to decide.

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destructive action. The description adds value by specifying the returned fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying that it lists active subscriptions by default, which aligns with the include_inactive parameter. 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 two sentences: the first defines the action and output, the second gives usage guidance. No wasted words, information is 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?

Given the simple nature of the tool (one optional parameter, no output schema, clear annotations), the description covers purpose, return fields, and usage guidance completely. No missing information for an agent to decide or invoke correctly.

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

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

Schema coverage is 100% with the single parameter already described. The description does not add additional meaning beyond stating 'active subscriptions' (which is already implied by the default false for include_inactive). No extra param semantics provided.

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

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

The description states a specific verb ('List') and resource ('the caller's active subscriptions'), clearly distinguishing it from sibling tools like 'subscribe' and 'unsubscribe'. It also lists the fields returned, adding specificity.

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: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This covers key usage contexts, though it does not explicitly exclude alternatives or name other 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?

Despite annotations being present, the description adds substantial behavioral context: rate limits (5 per identifier per day), free and non-quota-counting, claim_token flow for tracking, and the team's daily digest consumption. It sets realistic expectations about the feedback process and consequences, going well beyond the basic readOnlyHint/destructiveHint flags. No contradiction with annotations.

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

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

The description is well-structured and every sentence serves a purpose: purpose statement, usage conditions, exclusions, message guidelines, claim_token mechanics, and practical details (rate limit, quota). It is long but information-dense, front-loaded with the core purpose, and avoids fluff. The length is justified by the operational guidance needed for a feedback tool.

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

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

For a feedback submission tool with no output schema, the description covers all necessary context: what to report, when to use, scope boundaries, message format, claim_token tracking, and team response cadence. It fully answers the 'what happens after I submit?' question and gives the agent enough information to handle edge cases like unauthenticated submission. Complete for its complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the claim_token usage pattern (filing without an account returns a token, pass it back to read status) and clarifying message expectations ('Be specific (which tool, what error, what data was missing)'). It doesn't describe every parameter in prose, but the schema already does that; the extra context elevates it to a 4.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this as a feedback tool for Pipeworx tools, separating it from sibling query/research tools like ask_pipeworx and deep_research. It also explicitly scopes it to tools served by this Pipeworx connection, avoiding ambiguity with external MCP servers.

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 guidance is provided: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives clear when-not-to-use instructions, directing other-server issues elsewhere, and clarifies what to include in the message, making usage highly actionable.

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. Description adds that data is self-aggregating from CF analytics-engine, no PII, and cached 5min-1h. 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?

Three concise sentences, efficient use of bullet-pointed use cases, no redundancy. Every sentence adds value.

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

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

For a simple tool with one optional parameter and strong annotations, the description covers purpose, return values, use cases, data source, and caching. 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 covers the only parameter (window) with enum and description. Description adds nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds meaning beyond the schema.

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

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

The description clearly states the tool returns trending tools, packs, and call volume over a window. It uses specific verbs ('returns') and distinguishes from siblings like discover_tools (which is more about discovery, not trending).

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 three explicit use cases (discovering hot data, confirming canonical choice, aligning use case). Does not explicitly state when not to use or alternatives, but 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?

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial context: partition check logic, similarity threshold, fill check with realizable vs theoretical edge, and conditions to avoid trading. No contradiction with annotations; the description complements them.

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

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

The description is long but well-structured, starting with overall purpose, then detailing modes, partition check, and fill check. It uses subheadings and bullet points. While dense, every sentence adds necessary information for a complex tool.

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

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

Despite no output schema, the description details the response structure (opportunities[], partition_check with fields) and explains internal logic (monotonicity, partition sum, fill check). It covers input combinations, edge cases (placeholder slugs), and trade recommendations, making it comprehensive for a complex arbitrage tool.

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

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

Schema coverage is 100% with both parameters described. The main description provides deeper semantics: explains event mode accepts slugs/URLs and walks child markets, topic mode does cross-event scanning with similarity filtering. This adds value beyond the schema's brief descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It specifies the verb 'Find', the resource 'arbitrage opportunities on Polymarket', and distinguishes from siblings like polymarket_edges by detailing its unique methods.

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

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

The description explicitly says 'Call with NO args for a trending_scan... pass event for... or topic for...' and gives recommendations (event recommended for a specific market). It explains when not to trade via the fill check. However, it does not explicitly contrast with sibling tools like polymarket_edges or polymarket_fill_risk beyond mentioning the latter for custom sizing.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description goes far beyond, detailing three model families with their methodologies, edge computation, Kelly sizing, caching, and diagnostic outputs. 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 sections but is overly verbose, containing detailed algorithmic explanations that could be shortened. It front-loads the main purpose effectively.

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

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

Given the complexity and absence of an output schema, the description covers the response structure (by_segment, diagnostics) and explains the return fields. It could be more systematic but is fairly 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%, so each parameter already has a description. The description adds context on how parameters interact (e.g., min_kelly vs min_partition_leg_kelly) and the meaning of edge-related knobs, providing additional 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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and it is explicitly built for discovering betting opportunities. This distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 the tool is for discovering opportunities without paging hundreds of markets, but does not explicitly state when not to use it or compare directly to alternatives. The context of siblings is provided separately.

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 the tool as read-only, idempotent, and non-destructive. The description adds significant context: it uses daily snapshots, decay computed from daily closes (not intraday), history bounded by 60-day TTL, and explains that gaps in snapshot_dates mean no scan that day. No contradictions.

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

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

The description is detailed but somewhat lengthy. It is well-structured with purpose, usage example, args, and response breakdown, but could be more concise by trimming redundant phrasing.

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 response structure (tracked[], expired[], snapshot_dates[]) including fields like edge_pp_net time-series, trend, decay_pp_per_day, and lifespan_days. This compensates fully for the missing schema and makes the tool's output understandable.

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 each parameter having a description. The description adds context: days default 14, max 30, window default '1wk', and explains the meaning of 'window' as snapshot family. This provides useful guidance beyond the schema.

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

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

The description clearly states it provides 'Edge persistence and decay telemetry' from daily snapshots, answering how long an edge has existed and if it's shrinking. It distinguishes itself from sibling tool 'polymarket_edges' by focusing on temporal analysis rather than raw snapshots.

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

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

The description implies when to use the tool via the example of a fresh vs. old wide edge, and by listing parameters days and window. However, it does not explicitly state when not to use it or mention alternatives, leaving some room for ambiguity.

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, idempotentHint, and no-destructive. The description adds substantial behavioral context: it walks the order book ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, verdict, thin_legs, forced_directional_risk, and warns of the dominant loss mode from partial basket fills. This goes well 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 somewhat verbose but well-structured. It starts with the core purpose, then explains the two modes in separate paragraphs, and ends with a clear usage directive. Every sentence adds value, though it could be slightly more concise without losing information.

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

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

Given the tool's complexity (two modes, many return fields) and the absence of an output schema, the description is remarkably complete. It lists all key return fields for both modes, explains the verdict, profit, thin_legs, and forced directional risk. There are no obvious gaps for an agent to understand what the tool does and what it 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?

The input schema has 100% description coverage, but the description enriches parameter understanding. It explains that size_usd for basket is 'settlement notional — shares per leg', that side in basket defaults to auto based on partition sum, and that market and event are mutually exclusive (REQUIRES one of). This adds meaningful context beyond the schema.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and specifies it should be used before acting on arbitrage signals. This is a specific verb-resource pair that differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly provides usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the risks of partial fills converting arb to directional position, and details when to use single-market vs basket mode. This is comprehensive and clear.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral context: modes, response structure, safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype), and rare tradeability. 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 but well-structured with clear sections (modes, response, safety fields). It is front-loaded with purpose and every sentence adds value. Slightly verbose but justified given 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 the tool's complexity, no output schema, and rich annotations, the description covers all necessary aspects: modes, parameters, response format, safety fields, limitations, and temporal alignment. It is fully complete for agent decision-making.

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

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

Schema coverage is 100%, and the description adds substantial meaning: topic lists all 10 shortcuts, explicit parameters are explained with examples and override behavior. The description goes beyond schema to clarify usage.

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

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

The description clearly states it calculates cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on two specific venues and uses specific verbs and resource description.

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 explains two modes (topic and explicit), includes safety fields and warnings about compatibility and temporal alignment, and advises that most pre-mapped topics return warnings, guiding the agent to use explicit pairing when needed.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint. The description adds context about scoping to identifier and pairing with related tools. No contradictions. The additional behavioral details (scope, no modification) are useful 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 three sentences, front-loaded with the primary action, then use cases, scope, and pairing. No unnecessary words; every sentence adds value.

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

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

The tool has no output schema, but the description does not detail return format (e.g., value type, list format). However, for a simple key-value retrieval, the description is adequate given the annotations and simple schema. Some minor gap remains.

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

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

Schema coverage is 100%, and the schema description already explains that the 'key' parameter is optional and omitting it lists all keys. The description repeats this information without adding new meaning, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool retrieves a value saved via 'remember' or lists all keys if the key argument is omitted. It distinguishes from sibling tools 'remember' (save) and 'forget' (delete) by explicitly pairing them. Concrete examples (ticker, address, notes) further clarify the purpose.

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

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

The description explains when to use the tool: to look up stored context without re-deriving it. It implies alternatives by pairing with 'remember' and 'forget'. Could be more explicit about when not to use, but the context is clear.

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

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

Annotations already declare safe, idempotent, non-destructive behavior. The description adds valuable context: return fields (source, citation_uri, raw event), mark_read behavior affecting future calls, and polling compatibility. No contradictions.

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

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

Four sentences, front-loaded with core purpose. Each sentence adds value without fluff. Efficient structure.

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

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

Despite no output schema, the description explains return fields and notes an alternative HTTP endpoint. Covers filtering, mark_read, and polling suitability. Complete for a read-only 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% with parameter descriptions. The description adds meaning beyond schema, e.g., explaining mark_read flagging events as read and noting that filtering by type and since are available.

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

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

The description states a specific verb ('Pull') and resource ('fired events from your subscription feed'). It clearly distinguishes from sibling tools like 'list_subscriptions' by focusing on event retrieval rather than subscription listing.

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

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

Provides clear context for use (polling works fine, filtering options) and mentions an alternative access method (HTTP endpoint). However, it does not explicitly state when not to use this tool or directly compare to siblings like 'list_subscriptions'.

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

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

Describes fan-out to multiple data sources (SEC, GDELT/GNews, USPTO), fallback logic, and soft-fail for PatentsView. Adds context beyond annotations, which already indicate safety and idempotency.

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

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

Single dense paragraph with no extraneous information. Front-loaded with example queries, then details on data sources and parameters.

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?

Complex tool with multiple sources and fallbacks; description covers input patterns, parameter details, output structure (grouped changes with citation URIs), and links to sibling tool. No output schema present, but return format is adequately described.

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

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

Schema coverage is 100%, but description adds explanations for 'since' formats, constraints on 'type', and value examples. No ambiguity remains.

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

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

The description clearly states the tool provides a change feed for a company over a recent window, with explicit example queries. It distinguishes itself from the 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 when-to-use guidance by contrasting with 'entity_profile' for static profiles, and explains fallback behavior. Examples help the agent select correct parameters.

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

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

The description adds significant behavioral context beyond the annotations: it explains scoping by identifier, persistence differences between authenticated and anonymous sessions, and a 24-hour retention for anonymous users. 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 concise (three sentences) and front-loaded with the core purpose. Each sentence adds distinct information: purpose, usage guidance, storage mechanism, persistence, and companion tools. 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?

The description covers purpose, usage context, storage mechanism, scoping, persistence, and companion tools. It does not mention return values or error scenarios, but given the simplicity (two string params, no output schema), it is nearly complete. Minor gap: key collision behavior.

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

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

The input schema already provides detailed parameter descriptions with examples, covering 100% of parameters. The description does not add additional parameter-specific semantics; it only reinforces the key-value nature. Baseline score is appropriate.

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

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

The description clearly states the tool's purpose: saving data for later reuse. It provides concrete examples (resolved ticker, target address, user preference) and explicitly mentions companion tools (recall, forget), which helps distinguish it from siblings.

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') and gives examples. It also mentions pairing with recall and forget, but lacks explicit 'when not to use' instructions. Still, it is clear and helpful.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds rich behavioral detail: graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` identifiers, source labeling per identifier, and cascading internal lookups. 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 long but front-loaded with the core purpose and usage directive. The type-specific details are organized and each section carries necessary context for a multi-source tool, though a slight trim could be possible without losing value.

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

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

With no output schema, the description compensates by explaining return values (identifiers, source labels, unresolved list), edge cases (non-US issuers), and failure behavior (graceful degradation). It covers the tool's complexity thoroughly.

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

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

Schema coverage is 100% and the description supplements with concrete examples (AAPL, CIK, ISIN, 'ozempic'), accepted input formats, and per-type resolution behaviors. It clarifies non-obvious mappings like ISIN resolving to legal entity via GLEIF, 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 opens with concrete example queries and explicitly states the core purpose: resolving names to canonical/official identifiers required by other tools. It clearly distinguishes the tool by its role ('Use FIRST whenever you have a name but need an ID').

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

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

The description gives a clear trigger condition: 'Use FIRST whenever you have a name but need an ID.' It also notes the tool replaces multiple manual lookups, providing context for when it is valuable, but it does not explicitly list alternatives or exclusion 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?

The description thoroughly explains the tool's behavior: it calls ai_visibility_check per entity, returns ranked list with score, confidence, signal density. Annotations (readOnlyHint, idempotentHint, destructiveHint=false) align with the description. No contradictions. The description adds value beyond annotations by detailing the underlying mechanism and output structure.

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

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

The description is three sentences, front-loaded with the core purpose. Every sentence adds essential information: what it does, how it works, use case, output summary. No redundancy or fluff.

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

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

Given the tool has 4 parameters, no output schema, and moderate complexity, the description covers all necessary aspects: purpose, process, parameters (implicitly), return format, and use case. It does not mention error handling, but for a probing/aggregation tool, the description 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%, so baseline is 3. The description adds context for the 'entities' parameter by noting the first entry is treated as the 'subject' for narrative, which is not in the schema. For other parameters, the description reinforces the schema but doesn't add new semantic meaning. Overall, it provides moderate added 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 it 'Compare AI visibility across multiple entities side-by-side' and details the process: probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized. It distinguishes itself from the sibling 'ai_visibility_check' (single entity) and 'compare_entities' (generic) by specifying the AI visibility domain and multi-entity comparison.

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

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

The description provides a concrete use case: 'competitive AI-marketing audits' and an example question. It implies usage when comparing multiple entities for AI recognition, and the mention of 'ai_visibility_check' suggests this is a batching tool. However, it does not explicitly state when to use this vs. alternatives, nor provide exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds critical behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed lists timeouts while the rest still returns. This goes beyond annotations.

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

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

The description is multi-sentence but every sentence adds value: first sentence defines purpose, second gives usage examples, third details return format, fourth states ecosystem limitation and failure handling. No wasted words. Well-structured and front-loaded.

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

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

Given the tool is a composite with multiple data sources, the description covers all key aspects: what it checks (license, advisories, version history, bundle size, ESM/tree-shake), return content, partial failure behavior, ecosystem scope, and limitations. No output schema exists, so description fully describes 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%, so the baseline is 3. The description adds extra context: scoped packages (e.g., '@types/node') are accepted for 'package', and 'version' defaults to latest when omitted. This adds meaningful nuance 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 it's a composite check for 'should I add this npm package' covering license, advisories, version history, and bundle info. It uses a specific verb ('scan') and resource ('dependency') and distinguishes from siblings by focusing on npm packages, while other siblings are unrelated.

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

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

Explicitly says to use when an agent asks about safety, popularity, size, or cost of adding a package. Also specifies limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This provides clear context for when not to use.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive. The description adds technical details: embeddings model (BGE-base-en), window size (500-char overlapping), similarity metric (cosine), and character cap (200K with truncation and flagging). 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 that front-loads purpose and usage. Each sentence provides necessary information without redundancy. Slightly verbose but 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?

Despite lacking an output schema, the description fully explains return values (top-N passages with offsets and scores) and behavioral constraints (character cap, truncation). For a 3-parameter tool with rich annotations, this covers all needed context.

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

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

Schema covers all 3 parameters with descriptions. The description adds value by explaining 'text' as pre-fetched document, giving natural-language query examples, and noting 'limit' as max passages. This context aids correct usage beyond the schema.

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

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

The description clearly states the tool's function: semantic search inside a fetched record. It uses specific verbs like 'search INSIDE' and provides concrete examples (SEC 10-K, article). The tool is distinguished from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly states when to use: when the record is too large for the prompt. It explains benefits (saves context, returns only relevant passages with offsets for verification). Provides an alternative workflow with ask_pipeworx_grounded.

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

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

Annotations indicate readOnlyHint=false (write), openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral details: account requirement, phone verification for SMS, 10/day SMS cap, webhook auto-disable after 10 failures, and signing secret usage. However, it does not clarify idempotency behavior (e.g., whether duplicate requests create multiple subscriptions). Overall, it adds significant context beyond annotations.

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

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

The description is well-structured: first sentence states core purpose, followed by requirements, types with examples, and delivery details. It is front-loaded with the most critical information. Although somewhat lengthy (several sentences), each part adds necessary detail for a complex subscription tool with multiple types and channels. No redundancy or wasted words.

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

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

Given the moderate complexity (3 params, nested objects, multiple types) and lack of output schema, the description covers the main aspects: return value (subscription ID), account prerequisite, type-specific filters, and delivery behaviors (email, SMS, webhook with auto-disable). However, it omits error scenarios, rate limits beyond the SMS cap, and exact ID format. Still thoroughly covers the essential context 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 coverage is 100%, so baseline 3. The description goes far beyond schema descriptions by providing concrete examples for each type (e.g., sec_8k with items codes, polymarket_edge with topic and min_spread_bps), detailed delivery channel behavior (email validation, phone verification, webhook HMAC signing and auto-disable), and constraints like 'sponsor or condition required' for clinical_trial. This richly supplements parameter meaning.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' The verb 'create' paired with resource 'subscription' and specific context 'live-data event stream' makes the purpose unambiguous. It distinguishes from sibling tools like list_subscriptions or unsubscribe by focusing on creation.

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

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

The description provides clear context: requires Pipeworx OAuth account, lists supported types with examples, and describes delivery channels. However, it does not explicitly state when NOT to use this tool (e.g., if no OAuth account) or mention alternatives among siblings (e.g., recent_alerts for pulling). The guidance is strong but lacks exclusionary advice.

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, openWorldHint, idempotentHint, and non-destructive behavior. The description adds value by explaining that the tool returns example questions with exact tool+argument shapes from the live catalog, and that it is the onboarding entry point. No contradictions with annotations.

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

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

The description is a single paragraph but front-loaded with trigger phrases ("What can I ask Pipeworx?") and efficiently lists categories. Slightly verbose but each sentence provides value; no wasted words.

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

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

Despite the lack of an output schema, the description fully explains what the tool returns (category-bucketed example questions with tool+argument shape) and when to use it. Combined with rich annotations, the description is complete for this simple, read-only tool.

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

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

Schema coverage is 100% and baseline is 3. The description adds meaning beyond the schema by explaining the effect of omitting topic vs. passing a specific focus area (e.g., finance, pharma) and provides examples. It clarifies the parameter's optionality and behavior.

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

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

The description uses specific verbs ('returns', 'drawn from', 'call with') and clearly identifies the tool as the onboarding entry point for Pipeworx. It distinguishes itself from sibling tools like ask_pipeworx and entity_profile by focusing on example questions and tool usage guidance.

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 this FIRST when you do not yet know what Pipeworx can do for you' and explains when to omit vs. provide a topic argument. Also mentions alternatives implicitly by listing what the tool returns (calls to meta-tools like ask_pipeworx, entity_profile).

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

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

The description discloses ownership enforcement and deactivation behavior beyond what annotations provide. Annotations indicate readOnlyHint=false and destructiveHint=false, and the description confirms the operation is non-destructive (deactivates, not deletes), adding context about data retention.

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

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

The description is two sentences, front-loading the action and adding essential details without any unnecessary words.

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

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

Given the simplicity (1 parameter, no output schema), the description fully covers purpose, ownership, effect, and relationship to historical data, making it complete for the tool's complexity.

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

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

The schema covers 100% of the parameter 'id' with a description. The tool description doesn't add extra meaning beyond the schema, which is already clear. 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 'Cancel a subscription by id', providing a specific verb and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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 ownership enforcement ('you can only cancel your own subscriptions') and that the row is deactivated, not deleted, with historical events accessible via 'recent_alerts'. This gives clear context, though no explicit when-not-to-use statement is provided.

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

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

Discloses verdict taxonomy, the crucial distinction between could_not_verify (check did not happen) and unsupported (no source), and the verification_error object. This complements annotations (readOnly, openWorld, idempotent) 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?

The description is long but efficiently structured: leads with query phrasings, then purpose, pathways, return format, and a highlighted caller warning. Every sentence adds operational 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?

Despite lacking an output schema, the description fully covers return values (verdicts, actual value, citation, reasoning) and error semantics. It also explains the dual-pipeline behavior, making it self-sufficient for an agent to use correctly.

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

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

While schema covers both parameters, the description adds: tolerance_pct overrides implied tolerance, recommended 1–2 for hallucination detection, default capped at 5. Claim examples clarify expected input format beyond schema.

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

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

The description states a specific verb+resource: verifying natural-language claims against authoritative sources, with distinct execution paths for company-financial vs other claims. It distinguishes from generic Q&A by returning structured verdicts and evidence.

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' and details routing rules (SEC EDGAR fast path vs grounded pipeline). It also notes it replaces 4–6 sequential calls, guiding agents away from multi-step alternatives.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint = false. The description adds that it returns topic, start time, duration, etc., but these are standard for retrieval. No additional behavioral context 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 sentences: first states purpose and scope, second provides usage guidance. No unnecessary words, front-loaded with key action.

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

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

For a simple retrieval tool with one parameter and no output schema, the description covers purpose, usage context, and parameter reference. Annotations handle safety. Complete enough.

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 mentions 'meeting ID' but adds no new meaning beyond the schema's parameter description. 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?

Description starts with 'Get the full details of a single Zoom meeting by its meeting ID' which is a specific verb+resource. It lists the details included (topic, start time, etc.) and distinguishes itself from sibling tools like zoom_list_meetings by targeting a single meeting.

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 after zoom_list_meetings to inspect a specific video call.' This provides clear context for when to use the tool, though it does not explicitly mention when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety and idempotency. Description adds listing of returned fields, which is useful but does not significantly extend behavioral knowledge 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: first sentence lists returned fields, second sentence provides use case. No wasted words, front-loaded with purpose.

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

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

For a read-only, no-parameter tool, the description fully covers return values and usage context. No output schema needed; description suffices.

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

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

No parameters exist; schema description coverage is 100%. According to rules, zero parameters yield baseline 4. Description adds no parameter info, which is acceptable as none are needed.

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 verb 'Get' and resource 'signed-in Zoom user's profile', listing specific fields (id, email, name, etc.). This distinguishes it from sibling tools like zoom_get_meeting and zoom_list_meetings, which deal with meetings/recordings.

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 usage: 'Use to identify whose Zoom account is connected.' This provides clear context. No explicit when-not-to-use or alternatives, but given zero parameters and simplicity, it is adequate.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that it returns 'compact meeting summaries' with specific fields, and clarifies the type parameter's options. No contradictions.

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

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

Two sentences with key information front-loaded: what the tool does, what it returns, and when to use it. No superfluous content.

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

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

Given low complexity (2 optional params) and strong annotations, the description covers purpose, return fields, and usage. Could mention error cases or behavior with empty results, but not required.

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

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

Schema coverage is 100% with detailed descriptions for both parameters. The description reiterates the type enum values but adds no significant new semantics beyond the schema.

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

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

The description clearly states the verb (List), resource (Zoom meetings), and scope (signed-in user). It distinguishes from siblings like zoom_get_meeting (specific meeting) and zoom_list_recordings (recordings).

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

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

The description says to 'use to browse a user's Zoom meetings', providing clear context. It does not explicitly mention when not to use or alternatives, but sibling names implicitly guide the 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 indicate read-only, idempotent, non-destructive. The description adds that it returns specific fields and supports date range, but does not mention pagination behavior or exclusions like local recordings. 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?

Two sentences plus a terse imperative. Front-loaded with key info, 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?

With no output schema, the description lists returned fields helpfully. Covers core functionality for a list tool. Could mention error cases or empty results, but overall adequate.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds only that date range is optional, which is already in schema. No extra semantics beyond schema.

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

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

The description clearly states the verb 'List', the resource 'Zoom cloud recordings', and what it returns (id, topic, time, files). It distinguishes from siblings like zoom_list_meetings by specifying recordings.

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 says 'Use to find and access Zoom recordings' but does not explicitly state when not to use or contrast with alternatives like zoom_get_meeting. Some guidance is implied but incomplete.

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