Google_sheets

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

Annotations already indicate non-destructive, idempotent, read-only. Description adds that it's a probe (non-destructive), payment model for Anthropic, and return structure details (per-model scores, confidence, signals). 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-sentence description efficiently covers purpose, model options, return format, and use cases. Front-loaded with action, no filler. 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?

No output schema, but description explicitly states return format: per-model {score, confidence, signals, raw_response} + combined view. All 4 parameters explained, use cases given. Complete for this tool's complexity.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning: explains entity examples, free vs paid models, that _apiKey is passed through, and context disambiguates. Adds value beyond schema.

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

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

The description clearly states the tool probes LLMs for entity knowledge, returns visibility scores 0-100 per model, and specifies default model. It distinguishes from siblings like ask_pipeworx and deep_research by focusing on multi-model visibility scoring for brand audits.

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

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

Explicit use cases given: AI-marketing audits, pre-launch brand checks, competitive monitoring. Context on when to use Anthropic (requires key) and default free model. No explicit when-not or alternatives, but clear enough for selection.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context: routing across many tools, filling arguments, stable pipeworx:// citation URIs, and 'works on every tier, one fast call'. However, it does not disclose any limitations (e.g., latency, potential failure modes) beyond the positive behavioral traits.

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

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

The description is well-structured and front-loaded with the key directive 'PREFER OVER WEB SEARCH'. It packs domains, mechanism, examples, and alternatives into a dense but readable block. Every sentence contributes meaningful guidance; nothing is redundant or verbose.

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 general routing entry point, the description covers what it does, how it routes, examples, when to use, and when to escalate. It states the return format (structured answer with citation URIs) and references sibling tools appropriately. No output schema is present, but the description provides sufficient contextual completeness for an agent to invoke it 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 all parameters documented as aliases for 'question'. The description reinforces the natural-language nature with examples but adds no new parameter syntax or format details beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states it answers factual questions by routing to one of 5,529 tools across verified sources, returning structured answers with citations. It distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research, with a specific verb+resource scope.

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

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

Explicitly instructs to prefer over web search, provides trigger phrases ('what is', 'look up', 'find', etc.), and lists example questions. It gives clear escalation paths (ask_pipeworx_grounded for grounded answers, deep_research for multi-part) and notes coverage for breaking news, making when-to-use and when-not-to-use very clear.

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

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true, etc.), the description adds valuable behavioral context: it is an experimental edge with candidate routing improvements enabled live only when under test, the last candidate was retired on 2026-07-26, and it falls back to nothing (it is a full working router). This clarifies the tool's experimental nature and current state without contradicting annotations.

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

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

The description is compact at four sentences, front-loaded with the core definition of a beta universal router. It efficiently covers the current state, usage comparison, and the 'full working router' clarification without wasting words. It is slightly dense 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?

Given the tool's complexity (router to 5,529 tools) and lack of output schema, the description adequately covers purpose, behavioral state, usage, and comparison. It references 'same response shape' to inherit expectations from ask_pipeworx. This is sufficient for an agent to select and invoke the tool correctly.

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

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

The schema provides 100% coverage of all 6 parameters, all of which are aliases for the 'question' field. The description mentions 'same arguments' as ask_pipeworx, but this adds no new parameter semantics beyond the schema. Baseline 3 is appropriate because the schema already does the heavy lifting.

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

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

The description clearly defines the tool as a beta version of the ask_pipeworx universal router, noting it has the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable sibling ask_pipeworx by explaining that candidate routing improvements may be active, and it explicitly states it is a full working router. This gives a specific verb+resource+scope and differentiates it from alternatives.

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

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

The description gives explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' It also provides context that no candidate is currently active, so it matches ask_pipeworx exactly, and it names the stable alternative. This clearly explains when to use this tool versus the sibling.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses refusal reasons, return format, the hallucination-resistant behavior, and the extra LLM call cost. This gives the agent critical behavioral understanding that annotations alone would not provide.

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

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

The description is dense and packs a lot of information, but every sentence earns its place. It uses front-loaded core purpose and structured output examples. Slightly long but proportionate to the complexity of the tool's 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?

Despite lacking an output schema, the description fully specifies the success and refusal response shapes, lists all possible refusal_reason values, and gives concrete example use cases. For a single-question tool with no output schema, this is complete.

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

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

Schema coverage is 100% with all parameters being aliases for 'question'. The description does not add new parameter-level detail beyond the schema, which already fully documents the aliases. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description uses a specific verb+resource ('hallucination-resistant answer mode for high-stakes reads') and immediately contrasts with ask_pipeworx ('Same routing as ask_pipeworx'), distinguishing it from siblings. It clearly states its core function: extracting answers only from tool results and returning structured responses or explicit refusals.

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

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

Explicitly provides when to use ('whenever an answer will be quoted, cited, or acted on'), when not to use ('prefer ask_pipeworx for casual lookups'), and notes the cost tradeoff (one extra LLM call). No ambiguity about alternatives.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds extensive behavioral details: fan-out based on classification, response shape (market, analysis, evidence), resolver contract with confidence levels, parent event extraction, news fallback handling, safety short-circuits for low confidence/closed markets, illiquid spread tradeability notes, and cancellation rule parsing. All these go 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 well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loaded with the core purpose. Every section serves a purpose given the tool's complexity. While not minimal, it earns its length by providing necessary detail. A slightly tighter rewrite could improve conciseness, but it remains effective.

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

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

Given the tool's complexity (3 params, no output schema), the description is remarkably complete. It covers input handling, classification, fan-out logic, response structure, resolver confidence, parent event extraction, news fallback, safety mechanisms, and cancellation rule parsing. No significant gaps are apparent, making it sufficient for an agent to understand and 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?

Although all parameters have schema descriptions (100% coverage), the tool description adds substantial value: it explains the exact input formats for 'market' (slug, URL, question text) with examples; for 'depth' it clarifies 'quick = 2-3 evidence sources, thorough = full fan-out. Default thorough'; for 'include_raw' it details the size impact (20KB summary vs 50-500KB full payloads). This enriches the agent's understanding significantly.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). The verb 'research' combined with 'bet' gives specific scope, distinguishing it from siblings like 'ask_pipeworx' or '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 provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also includes strong guidance like 'ALWAYS inspect [market_match_confidence] before trusting the analysis block' and 'Check [cancellation rule] before sizing.' However, it does not mention alternatives among sibling tools, which would have made it a 5.

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

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

Adds substantial detail beyond readOnlyHint annotations: explains data source (SEC EDGAR/XBRL for companies, FAERS for drugs), specific metrics retrieved, handling of fiscal year differences, sorting by primary metric, and citation URIs. No contradiction with annotations.

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

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

Front-loaded with trigger phrases and primary purpose. Every sentence adds value, though slightly lengthy. Well-structured with type-specific details.

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

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

Given no output schema, description covers return format (paired data + citation URIs), data sources, metric types, and sorting behavior. Complete for a comparison tool with two entity types.

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%. Description enriches with examples ('AAPL','MSFT' for company; 'ozempic','mounjaro' for drug) and explains data retrieved per type, adding meaning beyond schema descriptions.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs in one parallel call, with specific verbs and resource types. It distinguishes from siblings like entity_profile by emphasizing 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?

Explicit triggers like 'Compare X and Y' and 'ALWAYS PREFER over sequential single-pack lookups' provide clear when-to-use guidance. Does not explicitly list when not to use, but the positive guidance is strong.

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?

With readOnlyHint=true and idempotentHint=true, annotations already declare safety. The description adds substantial behavioral context: it returns a findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], and hop fields; it never invents findings; it semantically excerpts large records instead of head-truncating; latency expectations are given (15-60s, up to ~90s for thorough). This is rich behavioral disclosure 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 dense and front-loaded with critical account-signup information, then flows into what the tool does, use cases, alternatives, depth semantics, and output details. Every sentence earns its place, and the structure is logical, but it is lengthy (several long paragraphs) and could be tightened; still, given the tool's complexity, the length is largely justified.

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?

This is a complex research tool with only 2 params and no output schema, so the description carries full burden for explaining behavior. It covers output format, citation resolvability, gap and contradiction handling, excerpting strategy, latency, account tiers, and alternative tools. For a tool with no output schema, this is remarkably complete — an agent could invoke this correctly and set correct expectations for results.

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

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

Schema coverage is 100%, so baseline is 3. The description adds genuine meaning to both parameters: it explains that 'question' can be broad/multi-part and decomposition is the point, and it elaborates on the 'depth' enum values with facet counts, hop behavior, gap recovery, contradiction scanning, and paid-tier requirements. This exceeds schema-only semantics.

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

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

The description clearly states the tool performs grounded multi-source research across 1,455 structured data sources, decomposing questions into facets and routing them to 5,529 tools in parallel. It explicitly distinguishes itself from open-web search and from sibling tools like ask_pipeworx, naming specific use cases and comparing against alternatives.

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 is exceptionally explicit: it says sign-in is required, states to use ask_pipeworx if not signed in, recommends deep_research for broad/multi-part questions, and advises ask_pipeworx for breaking/current-news topics or single lookups. It even explains depth levels and second-hop iteration behavior, giving clear when-to-use versus when-not-to-use guidance.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds that it returns top-N tools with full schemas and examples, ready to call, providing behavioral context beyond annotations.

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

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

The description is a single paragraph that front-loads purpose and conveys necessary information efficiently, though it could be slightly more concise.

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

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

Given no output schema, the description adequately explains the return value (top-N tools with schemas) and usage. It covers the tool's role in the context of many 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?

Schema coverage is 100%, so baseline 3 is appropriate. The description does not add significant per-parameter semantics beyond what the schema already provides.

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

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

The description clearly states the tool finds tools by describing data or task, lists numerous domains, and distinguishes itself from sibling tools by explicitly advising to call it FIRST when many tools are available.

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 indicates when to use (browse, search, discover) and advises calling it first when exploring many tools, but does not explicitly state when not to use it or mention alternatives.

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

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

Annotations (readOnly, idempotent, non-destructive) are complemented by description details: parallel call, soft-fail for patents API sunset, return fields, and input constraints. No contradictions.

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

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

The description is long but well-structured and front-loaded with example queries. Every sentence adds value; could be slightly more concise but still effective.

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

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

Despite no output schema, the description thoroughly explains return fields, limitations (patents API sunset), and input constraints. It's complete for a complex multi-source 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 description adds examples and context (e.g., ticker vs CIK, names unsupported). This adds value beyond schema definitions, justifying a score of 4.

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

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

The description clearly states 'full cross-source profile of a US public company in ONE parallel call' and lists all data sources and returned fields. It distinguishes from chaining individual lookups and from sibling tools like resolve_entity.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and provides guidance on when to use resolve_entity for names. This gives clear when-to-use and alternatives.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description's 'delete' aligns. Adds context about clearing sensitive data but doesn't introduce new behavioral traits 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?

Two succinct sentences front-loading the action and usage guidance. No wasted words.

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

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

For a simple tool with one parameter and no output schema, the description adequately covers purpose, usage, and behavior. Could add more on consequences of deletion, but annotations already address destructiveness.

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

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

Schema coverage is 100%, and parameter description 'Memory key to delete' matches schema. Description adds no extra meaning beyond schema; baseline 3 is appropriate.

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

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

Description clearly states 'Delete a previously stored memory by key,' specifying verb and resource. It distinguishes from sibling tools like remember and recall by explicitly mentioning them.

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 conditions for use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also advises pairing with remember and recall, offering clear context on 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?

Beyond annotations (readOnly, idempotent, non-destructive), the description details the process: fetches page, extracts title/description/links, emits markdown. This adds valuable behavioral context that annotations alone do not cover.

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

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

The description is concise with three sentences covering purpose, process, and use cases. It is well-structured but could be slightly improved with bullet points or clearer separation of sections.

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

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

No output schema is present, but the description explains the output format and usage context thoroughly. For a simple tool with clear purpose, it provides sufficient completeness.

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?

Both parameters have schema descriptions (100% coverage), so the description adds little beyond noting url and max_links as inputs. No additional semantic meaning is provided.

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

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

The description clearly states the tool generates a 'production-ready llms.txt file' for any URL, specifying the verb (generate) and resource (llms.txt). It distinguishes from siblings by focusing on llms.txt generation, a unique capability among the listed tools.

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

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

The description explicitly lists three use cases: getting a client site indexed, drafting for own project, auditing competitor AI visibility. It does not, however, explicitly state when not to use or compare directly to sibling tools.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds the return field details, which is helpful but not extensive. No additional behavioral traits (e.g., pagination limits) are disclosed.

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

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

Two sentences that are front-loaded and efficient: first sentence states purpose and returns, second gives usage guidance. No redundant language.

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

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

For a simple list tool with no output schema, the description covers purpose, return fields, and usage adequately. It does not mention pagination or error handling, but these are not critical for this tool's simplicity.

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% (one parameter with clear description). The description does not add extra meaning beyond the schema; it reinforces the concept of 'active subscriptions' but the parameter is already well-documented.

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 'List the caller's active subscriptions' with clear verb and resource. It also enumerates return fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

The description provides clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It implies when to use but doesn't explicitly mention alternatives or 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 provide no safety hints (all false), so the description carries full burden and excels. It discloses rate limiting ('5 per identifier per day'), that it's free and doesn't count against quota, the unauthenticated flow returning a claim_token for later retrieval, and instructs users to describe issues in terms of Pipeworx tools/packs while avoiding pasting end-user prompts. This far exceeds typical transparency expectations.

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?

Though the description is lengthy, every sentence serves a purpose: purpose, usage triggers, exclusion scope, feedback etiquette, claim_token mechanism, rate limits, and team process. It is front-loaded with the most critical information and maintains coherent logical flow without 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's moderate complexity (4 optional params, nested object, no output schema), the description covers all critical contexts: how to file, what happens without an account, how to later retrieve status, usage boundaries, and constraints. It lacks nothing essential for an agent to correctly invoke and reason about the tool.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds no significant param-level detail beyond the schema; it mentions claim_token flow and general guidance, but the schema already thoroughly explains each parameter (type enum, context object, message constraints, claim_token usage). The description does not compensate for any schema gap because none exists, but it also doesn't add extra semantics beyond what structured fields provide.

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

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

The description opens with a specific verb phrase 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly identifying the tool's resource (Pipeworx feedback) and action (send feedback). It further enumerates distinct feedback types (bug, feature/data_gap, praise), and distinguishes itself from sibling tools by explicitly scoping to Pipeworx-owned tools, preventing confusion with other 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?

The description explicitly states when to use the tool: '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 provides a clear exclusion and alternative: for tools from a different MCP server, 'file it with that server instead,' and gives a decision heuristic ('Not sure? Pipeworx tool names are the ones this connection lists').

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

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

Annotations declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable context: data source (CF analytics-engine), privacy (no PII), output structure (pack, tool, count), and caching (5min-1h). This goes well beyond the annotations without contradicting them.

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

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

The description is well-structured with bullet points and parentheticals, and front-loads the main action. However, it is slightly verbose with multiple use cases and extra details that could be more concise. It earns its place but has minor 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 one optional parameter, no output schema, but rich annotations, the description covers the return structure (top tools, top packs, total call volume), caching, and data source. It is adequate for an agent to understand what to expect, but a more detailed return format example could improve completeness.

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

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

The schema already provides a detailed description of the single parameter 'window' (enum values, default, and usage guidance). The tool description does not add any new parameter semantics beyond what is in the schema. With 100% schema coverage, baseline is 3.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' derived from 'what other AI agents are calling on Pipeworx'. It specifies the resource (trending usage data) and the action (returns). The three use cases further clarify its purpose and distinguish it from siblings like discover_tools.

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

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

Three explicit use cases are listed: discovering hot data sources, confirming canonical tools, and seeing alignment. The description also advises on window selection. However, it does not explicitly state when not to use this tool or compare it to alternatives that might be more appropriate for other scenarios.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds rich behavior: explains SEMANTIC ANCHOR (Jaccard similarity), PARTITION FILTER (placeholder filtering), FILL CHECK (realizable edge at book depth), and conditions to avoid trading. 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?

Well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Each sentence adds value; no fluff. Front-loaded with purpose and mode overview.

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

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

Despite no output schema, the description fully details the response structure (opportunities[], partition_check, fill_check) and explains complex behaviors. Extremely complete for a moderately complex tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description goes far beyond schema by detailing mode selection, recommended usage, partition_check logic, cross-event scanning, similarity thresholds, and fill-check integration.

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 ('Find') and resource ('arbitrage opportunities on Polymarket'), and clearly distinguishes itself from sibling tools like 'polymarket_edges' by specifying the methods ('monotonicity violations + partition-sum checks').

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

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

Explicitly tells when to use each parameter: no args for trending scan, 'event' for specific market (recommended), 'topic' for cross-event scan. Also points to 'polymarket_fill_risk' for custom sizing, providing clear 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?

The description goes far beyond the annotations (readOnlyHint, idempotentHint, destructiveHint). It details caching behavior (cached 1h), response structure (by_segment with three segments), specific model families, and a 24-hour move warning. It also explains diagnostic fields that help understand empty results. 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 lengthy but well-structured with clear sections (models, response, diagnostics, knobs). Every sentence adds information, though the density could be overwhelming. It is front-loaded with the core purpose and use case, making the key intent clear quickly.

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 (9 parameters, no output schema, but rich annotations), the description provides exhaustive detail. It explains return structure, diagnostics, caching, and even gives specific model details (like Kelly caps, parameter defaults). This compensates for the lack of an output schema and ensures the agent can use the tool correctly.

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

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

Schema coverage is 100%, so all parameters have descriptions in the schema. The tool description adds value by explaining the rationale behind tradeable-edge knobs (e.g., slippage_pp mentions Polymarket's zero fees but typical bid/ask impact), and how min_partition_leg_kelly interacts with partition arbs. This contextual information enhances understanding beyond the schema.

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

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

The description clearly states that the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It specifies the verb 'scan' and resource 'Polymarket markets', and the unique value proposition distinguishes it from sibling tools like polymarket_arbitrage and 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 explicitly frames the tool as 'built for what should I bet on today' and explains that agents can discover opportunities without paging through hundreds of markets. It provides context on when to use (daily bet discovery) and even warns about Fed bets being excluded. However, it does not directly compare with sibling tools or list alternatives 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 already mark the tool as read-only and idempotent. The description adds significant behavioral context: decay is computed from daily closes (not intraday), history is bounded by snapshot TTL, and the response includes fields like trend and decay_pp_per_day. 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 well-structured, starting with the purpose and moving to args, response structure, and limits. It is somewhat verbose, as the response format details could be in an output schema, but every sentence adds value. No wasted words.

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

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

Given no output schema, the description fully explains the response: tracked, expired, snapshot_dates. It also covers limits (TTL, snapshot start). The agent has all necessary context to understand what the tool returns and its constraints.

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 repeats the parameter defaults and options almost verbatim from the schema. It adds no new semantic meaning, such as how days impacts the number of snapshots or the effects of different windows.

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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question and distinguishes itself from sibling tools like polymarket_edges, which likely provides raw edge data rather than persistence analysis.

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

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

The description provides a concrete use case: differentiating a fresh wide edge from a 3-week-old one. It also notes limits like the 60-day TTL. However, it does not explicitly contrast with alternatives or state when not to use this tool, relying on the purpose clarity to 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 declare readOnlyHint and idempotentHint, so safety profile is clear. Description adds behavioral details: walks the ladder, returns verdict and metrics, and explains the dominant loss mode (partial basket fills). 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?

Long but dense with information; uses bold and capitalization for key terms. Every sentence is earned given the tool's complexity, but could be more structured (e.g., bullet points). Still concise for the 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?

No output schema, but description enumerates return fields for both modes in detail (top_of_book, vwap_fill_price, slippage_pp, etc.), explains forced_directional_risk, and covers edge cases. Complete for a complex tool with 4 params.

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 parameters (100%). Description adds meaning: explains mode logic for side auto, interpretation of size_usd differently per mode, and defaults. Provides context beyond schema.

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

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

Clearly states it performs a realizable-vs-theoretical edge check against live CLOB order-book depth. Distinctly separates single-market and basket modes, and names sibling tools (polymarket_arbitrage, polymarket_edges) for context. The verb 'fill risk check' and resource 'Polymarket order book' are specific.

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

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

Explicitly says to use before acting on polymarket_arbitrage signals or any trade above ~$500. Warns that partial basket fills convert an arb to an unhedged directional position, explaining when not to use or what to watch for. Excellent guidance.

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

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

Beyond annotations (readOnly etc.), the description details behavioral traits: compatibility_warning, temporal_alignment, skipped_cross counters, and meanings. There is 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?

Well-structured and front-loaded with purpose, but somewhat dense. Could be slightly more concise without losing important details.

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

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

Without output schema, the description compensates by explaining response fields (top_spreads_pp, compatibility_warning, temporal_alignment) and error conditions. Covers edge cases like non-equivalent bet shapes and temporal gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the two modes and listing the 10 topic shortcuts explicitly, which goes beyond schema descriptions.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies the verb 'cross-venue spread' and distinguishes from sibling tools like polymarket_arbitrage.

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 two-mode usage (topic shortcuts or explicit events) is provided. The description warns that most pre-mapped topics return compatibility warnings, setting expectations. However, it could be more explicit about when not to use this tool vs alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds value by specifying scoping ('your identifier') and list behavior. No contradictions with annotations.

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

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

Three sentences, front-loaded with core action. Every sentence adds value without redundancy. Exceptionally concise.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers purpose, when-to-use, behavioral scope, and related tools. No gaps.

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

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

Schema coverage is 100% and includes the 'omit to list all keys' detail. The description restates that but adds usage context. Baseline 3 is appropriate.

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

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

Clearly states the verb 'retrieve' and resource 'saved memory'. Distinguishes itself from sibling tools 'remember' and 'forget' by mentioning them. Also explains the list-all-keys behavior when key is omitted.

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

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

Explicitly provides when to use: 'to look up context the agent stored earlier' with concrete examples. Mentions scoping and pairing with remember/forget. Could be improved by noting when not to use (e.g., when you need to search across identifiers).

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 mark_read behavior and payload structure, but annotations indicate readOnlyHint=true, while description allows flagging events as read (a state change). This is a clear contradiction between annotation and description, reducing trust.

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 paragraphs, first sentence clearly states purpose. Includes return value details and alternative access, which is helpful but slightly wordy. No wasted sentences.

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

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

Covers return fields (source, citation_uri, payload), filtering, mark_read semantics, and alternative access. Lacks mention of pagination or rate limits, but given no output schema and 5 parameters, it's reasonably 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%, and description adds value by providing examples ('sec_8k') and clarifying that since expects ISO timestamp and mark_read behavior. This goes beyond the schema's bare descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed, using specific verb ('Pull') and resource ('subscription feed events'). It distinguishes from siblings like 'list_subscriptions' (which lists subscriptions themselves) by focusing on actual fired events.

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

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

Provides context on using mark_read to control what's returned next and mentions polling suitability. Also gives an alternative API endpoint for scripts. However, lacks explicit comparison to aid selection among sibling tools like 'recall' or 'recent_changes'.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral details: fans out to multiple sources (SEC, GDELT/GNews, USPTO), includes fallback logic (GDELT preferred, GNews when rate-limited), and mentions soft-fail for patents. 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, well-structured paragraph. It front-loads example queries, then explains behavior, parameters, and return structure. Every sentence adds value with no redundancy.

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

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

Given the tool's complexity (multi-source, fallback, no output schema), the description is complete. It explains input parameters, multi-source fan-out behavior, fallback logic, and return structure (changes[] grouped by source + total_changes + citation URIs).

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

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

Schema description coverage is 100%, but the description adds further meaning: explains 'since' accepts ISO date or relative shorthand, recommends '30d' or '1m', and clarifies 'value' can be ticker or CIK. This adds 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 uses specific verbs ('change feed', 'fans out') and clearly states the tool provides recent updates for a company. It distinguishes from sibling tool entity_profile by explicitly mentioning when to use that instead.

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

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

The description gives clear use case examples ('What's new with X', 'latest on Y') and provides explicit guidance on when not to use this tool ('Use entity_profile instead when you want the static profile'). It also advises on the 'since' parameter.

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 idempotentHint and destructiveHint, but description adds valuable context: data is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours. 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 moderately concise; front-loads the main purpose. Each sentence adds value, though some minor redundancy ('across this conversation or across sessions') could be tightened. Overall well-structured.

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

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

For a simple key-value store with 2 parameters and no output schema, the description is complete. It covers purpose, usage timing, pairing with siblings, and persistence behavior. No gaps given 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% and schema descriptions are adequate. Description adds example key patterns ('subject_property', 'target_ticker') which provide mild additional context, but does not significantly enhance parameter understanding beyond schema.

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

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

Clearly states the tool saves data for reuse across conversations/sessions. Distinguishes from siblings 'recall' and 'forget' by mentioning pairing. Specific verb 'save' with resource 'key-value pair'.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and advises pairing with 'recall' to retrieve and 'forget' to delete. Also explains persistence differences for authenticated vs anonymous sessions.

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

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

Beyond the readOnly/idempotent annotations, the description discloses important behavioral traits: graceful degradation when GLEIF/OpenFIGI are unavailable, explicit labeling of unresolved identifiers, and internal cascading across multiple endpoints. It also describes output format (canonical IDs with source labels) and failure behavior (unresolved stated explicitly). 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?

Though lengthy, the description is well-structured with examples first, followed by SUPPORTED TYPES and behavior notes. Every sentence adds useful information, and the content is front-loaded with the most important usage guidance. It is detailed but not bloated given the tool's complexity.

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

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

The description is complete for a tool with no output schema: it covers supported entity types, input formats, expected output identifiers, source labeling, degradation behavior, and the fact that it replaces multiple manual lookups. There is no ambiguity about what the tool returns or how it behaves under partial failures.

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

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

Schema already covers both parameters well (type enum with descriptions, value with examples). The description adds value by explaining input variations (ticker, CIK, or name for company; brand/generic for drug) and detailing what the output will include (CIK, ticker, LEI, FIGI, RxCUI). This enriches the schema without redundancy.

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

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

The description clearly states the tool's function: resolving user-spoken names to canonical/official identifiers that other tools require. It uses a specific verb ('resolve') and resource ('entity'), provides concrete query examples ('What's the ticker for…'), and distinguishes from siblings by stating '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 provides explicit guidance on when to use the tool ('Use FIRST whenever you have a name but need an ID') and what it replaces ('replaces 2-3 manual lookups'). It does not explicitly state when not to use it or mention alternatives like compare_entities, but the context is clear and prioritized.

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, idempotentHint, openWorldHint, and non-destructive. The description adds details: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density. No contradictions; adds value beyond annotations.

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

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

Two sentences, front-loaded with the primary action ('Compare AI visibility across multiple entities side-by-side'). Every sentence serves a purpose, no redundancy. Efficient and clear.

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

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

With no output schema, the description explicitly lists return values (ranked list with score, confidence, signal density). It covers the tool's essential behavior and parameters, making it complete for an agent to understand what to expect.

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

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

Schema coverage is 100%. The description adds meaning: 'entities' first entry treated as subject, 'context' disambiguates common names. While not exhaustive, it supplements the schema with useful context.

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 compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and identifies most/least recognized. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic 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 clear use case: 'competitive AI-marketing audits' with an example question. It implies when to use (comparing multiple brands) but does not explicitly state when not to use or list alternatives, though siblings are available.

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

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

Annotations already cover read-only, idempotent, and non-destructive nature. Description adds valuable behavioral details: partial failures degrade gracefully, bundlephobia first measurement may take 5-30s, and sources_failed lists timeouts. Doesn't cover rate limits or auth, but sufficient given 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 moderately long but every sentence adds value. It is front-loaded with the core composite check purpose. Could be slightly more concise, but the detail is justified for a composite 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 enumerates return fields: summary block (specific fields listed), per-advisory detail, links, and alternative versions. It also notes NPM-only scope and graceful degradation. 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?

Input schema covers both parameters with descriptions (100% coverage). Description adds extra meaning: version defaults to latest if omitted, scoped packages (e.g., '@types/node') are accepted. This clarifies 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 it's a composite check for npm packages covering license, advisories, version history, bundle size, etc. It distinguishes from siblings by specifying NPM ecosystem and referencing deps.dev:version for other ecosystems.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. It also specifies scope (NPM only) and directs to deps.dev:version for other ecosystems, helping the agent decide when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. Description adds valuable technical details: embedding model, sliding windows, character cap with truncation flag. No contradictions. Good depth beyond annotations.

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

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

Description is a single paragraph of moderate length. Front-loaded with the main purpose and key use case. Every sentence serves a purpose (use case, benefits, technical details). No fluff. Good 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?

No output schema, so description explains return values: 'top-N passages with character offsets and similarity scores'. Also mentions truncation handling and pairing with another tool. For a tool of this complexity, the description covers essential aspects.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. Description adds practical examples for 'query' and a size hint for 'text' (max ~200K chars). This adds some context but does not substantially extend beyond the schema. Baseline 3 is appropriate.

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

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

Description states 'Semantic search INSIDE a fetched record' with verb 'search' and resource 'record'. It clearly distinguishes the action but does not explicitly contrast with sibling tools beyond mentioning 'ask_pipeworx_grounded'. Overall clear and specific.

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

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

Description explicitly tells when to use: 'Use when the record is too big to cram into the prompt'. It provides an alternative: 'Pairs with ask_pipeworx_grounded' and explains the benefit of using search_within first. Excellent 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 indicate idempotentHint=true and readOnlyHint=false. The description adds no new behavioral context (e.g., that multiple calls may duplicate rows, or that the table must exist). 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 one sentence, highly concise, but omits important details that could be included without excessive length. It is front-loaded but not optimally informative.

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

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

Given the output schema exists, return values are covered. Parameters are documented. However, missing context includes idempotent behavior effects and prerequisite that the sheet/table must exist. Adequate but not 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?

Input schema covers 100% of parameters with descriptions. The description adds 'sheet name and row data' which matches 'range' and 'values', but does not add meaning beyond the schema for 'spreadsheet_id' or 'value_input_option'. Baseline of 3 is appropriate.

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

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

The description clearly states the verb 'append' and the resource 'Google Sheet table', and it distinguishes from sibling tools like sheets_read and sheets_write by specifying 'append to the end of a table'. However, it could be more precise about the 'table' concept.

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

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

The description implicitly indicates use for adding rows, but provides no explicit when-to-use or when-not-to-use guidance compared to siblings like sheets_write (which might overwrite) or sheets_create (for new sheets).

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 claims 'Create a new Google Spreadsheet' implying each call creates a distinct spreadsheet, but annotations set idempotentHint=true, suggesting repeated identical calls have the same effect. This contradiction is not addressed. No disclosure of authorization needs or rate limits.

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

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

The description is a single concise sentence, but it contains inaccuracies (title optional) that undermine its effectiveness. It is short but not clear enough to be reliable.

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 existence of an output schema, the description adequately notes return values. However, it fails to explain idempotency behavior, error handling, or constraints like duplicate titles, leaving gaps for a tool with complex annotations.

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

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

The description states that title is optional and mentions 'initial sheet names', but the schema marks title as required and does not include a sheet names parameter. This misleads the agent about required inputs and available options.

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 creates a new Google Spreadsheet and returns ID and URL, distinguishing it from sibling tools like sheets_read or sheets_write. However, it mentions 'initial sheet names' which is not reflected in the input schema, causing minor confusion.

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

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

No explicit guidance on when to use this tool versus alternatives like sheets_get_spreadsheet or sheets_append. The description does not mention prerequisites or scenarios where other tools would be preferable.

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 specify readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds that it returns title, sheet/tab names, and properties, which is consistent but does not introduce new behavioral traits beyond what annotations imply.

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

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

Two concise sentences: first states function, second gives usage advice. No redundant or unnecessary information, each sentence earns its place.

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

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

The tool is simple with one parameter and an output schema (not shown). Description mentions key return items (title, names, properties), which is sufficient. Could be slightly more specific about 'properties,' but overall complete given context.

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

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

Schema coverage is 100% and the only parameter 'spreadsheet_id' is described as 'Spreadsheet ID' with an example. The description does not add additional meaning or formatting requirements beyond the schema.

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

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

Description explicitly states the tool explores spreadsheet structure and lists return items (title, sheet/tab names, properties). It also suggests a use case before reading/writing, clearly distinguishing it from sibling tools like sheets_read, sheets_write, sheets_append.

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

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

Description explicitly states 'Use before reading or writing data,' providing clear context for when to use. While it does not mention alternatives, the usage guidance is direct 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 cover readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description adds value by specifying the return format ('Returns rows as arrays of cell values'). No contradictions with annotations.

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

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

The description is two sentences with no extra words. It is front-loaded with the core action and then the return format. Every sentence is necessary.

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

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

Given the presence of an output schema and comprehensive annotations, the description is complete enough for this read-only tool. It specifies the range format and return type, which suffices for agent selection.

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 description adds little beyond the schema. The example of range notation ('A1:C10') is already in schema examples. No additional parameter semantics are provided.

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

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

The description clearly states 'Read data from a Google Sheet range,' specifying the verb (read) and resource (Google Sheet range). It provides an example of notation ('A1:C10') which distinguishes it from sibling tools like sheets_write and sheets_append.

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 reading data, which is distinct from sibling tools that write or append. It does not explicitly state when not to use or provide alternatives, but the verb 'Read' clearly sets 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 provide readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds that it 'overwrites existing values', which is consistent. However, it does not add significant behavioral context beyond what annotations already convey, such as authentication needs or rate limits.

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

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

The description is a single, efficient sentence that front-loads the purpose and includes a concrete range example. Every word earns its place, with no fluff or redundancy.

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

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

Given the complete schema with examples and the existence of an output schema, the description sufficiently covers the tool's purpose and basic usage. It explicitly mentions the key parameters (sheet name, range, row data) and the fact that it overwrites, which is the core functionality.

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

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

Schema description coverage is 100% with detailed parameter descriptions and examples. The description merely summarizes parameters ('Specify sheet name, range, and row data') without adding new semantic meaning beyond what the schema provides.

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

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

The description clearly states the tool writes data to a Google Sheet range and overwrites existing values. It uses a specific verb ('write') and resource ('Google Sheet range'), and distinguishes itself from sibling tools like sheets_append and sheets_read by explicitly mentioning overwriting.

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 this tool (when overwriting values) but does not explicitly contrast with sheets_append for appending rows or provide when-not-to-use guidance. The differentiation is implicit through the word 'overwriting', but no alternative tools are named.

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

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

The description states 'Returns the new subscription id,' implying each call creates a new subscription, which contradicts the idempotentHint: true annotation. Despite adding other behavioral details (auth requirements, delivery constraints, SMS cap, webhook auto-disable), the contradiction with annotations forces a score of 1.

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

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

The description is well-structured with clear sections for types and delivery. It front-loads the purpose and uses bullet-like formatting. While it is somewhat lengthy, every sentence adds value and the structure aids readability.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description covers essential aspects: return value, type-specific parameters, delivery channels, auth requirements, and constraints. It lacks error handling details but is otherwise comprehensive.

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 coverage is 100%, but the description adds significant meaning beyond the schema by providing examples for each type, explaining special fields (items, topic, series_id), and detailing delivery options. This extra context helps the agent understand parameter usage.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses specific verbs and resource, and distinguishes itself from siblings like list_subscriptions and unsubscribe.

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

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

The description explains when to use this tool and includes important preconditions (requires OAuth account, anonymous/BYO cannot persist). It also details supported types and delivery channels. However, it does not explicitly contrast with alternative tools like recent_alerts for pulling, though that is implied.

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 that the tool returns example questions drawn from a live catalog, with exact tool and argument shapes. Annotations already indicate read-only, idempotent behavior; description adds valuable detail about what the output contains and how it is structured.

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

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

Description is front-loaded with common question phrases and clearly structured. Slightly verbose with the parenthetical list of categories, but each sentence adds value. Could be tightened without losing clarity.

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

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

Given the tool's role as an onboarding entry point and the presence of many sibling tools, the description fully covers purpose, usage, parameter, and output nature. No output schema exists, but description compensates by describing the return format.

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 single optional parameter with a description; the description adds concrete values (e.g., 'finance', 'pharma') and explains that omitting topic returns a full cross-category spread. No ambiguity.

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

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

The description clearly states it is the onboarding entry point, listing alternative question phrasings and specifying its function: returning category-bucketed example questions with exact tool+argument shapes. It distinguishes from siblings like ask_pipeworx and entity_profile.

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

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

Explicitly tells the agent to use this tool FIRST when unsure what Pipeworx can do, and explains how to focus via the topic parameter. Provides clear when-to-use and optional filtering 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 provide readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds valuable context: ownership enforcement, deactivation instead of deletion, and that historical events remain via recent_alerts. 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?

Two sentences, front-loaded with action, efficient. Every sentence adds value without redundancy.

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

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

For a simple cancellation tool with good annotations, the description covers purpose, ownership, side effects, and cross-reference to recent_alerts. Minor gaps: no error handling or invalid id mention, but overall 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 coverage is 100% and the id parameter is well-described. The description adds no new meaning beyond 'by id'. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Cancel' and resource 'subscription by id', distinguishing it from siblings like 'subscribe' (create) and 'list_subscriptions' (list). Ownership enforcement and deactivation details add 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 explicitly says 'you can only cancel your own subscriptions,' giving a condition for use. It implies usage for canceling subscriptions but does not directly compare to alternatives or exclude cases.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, but the description adds critical behavioral nuance: 'could_not_verify' means the check did not happen and carries verification_error, not evidence for/against the claim; 'unsupported' means no source covers it; returns a specific verdict set, citation, and reasoning. 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 well-structured and front-loaded with natural-language trigger phrases. Each sentence adds value, though the 'Replaces 4–6 sequential calls' sentence is more of a performance claim than core API guidance; it is still useful but could be trimmed without losing essential information.

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

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

With no output schema, the description fully explains the return values (verdict options, actual value, citation, reasoning) and the distinction between failure modes. It covers edge cases like could_not_verify and unsupported, and clarifies the tool's scope, making it complete for an AI agent to invoke correctly and interpret results.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: it explains how tolerance_pct overrides the tolerance implied by claim wording, recommends 1–2 for hallucination detection, and notes the default cap of 5. It also gives concrete examples of claim types and clarifies what the structured vs grounded paths mean for the claim input.

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: 'validate', 'verify', 'fact check' and clearly identifies the resource: natural-language factual claims against authoritative sources. It differentiates from siblings by describing two distinct pipelines (SEC EDGAR/XBRL for company-financial claims, grounded pipeline for all others) and explicitly states it replaces 4–6 sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides routing rules (company-financial claims vs any other claim). It does not name alternative sibling tools, but the routing and scope are clear enough to avoid confusion with research or comparison tools.

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