Quickbooks

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral context: probes one or more LLMs, defaults to workers-ai, passes _apiKey to Anthropic directly, and returns per-model fields. It also notes that Anthropic calls are billed separately, which is useful beyond annotations.

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

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

Four front-loaded sentences with zero waste. First sentence states core function. Subsequent sentences add key details (default, optional Anthropic, return structure, use cases). Information density is high and 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 4 required parameters (1 required), no output schema, and moderate complexity, the description covers usage, parameter roles, return format (per-model fields + combined view), and pricing implications. Lacks details on potential errors or rate limits, but these are acceptable gaps for a simple probe tool.

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

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

Schema coverage is 100%. The description adds value: explains that 'workers-ai' is free, '_apiKey' is only needed for Anthropic, 'models' can be omitted for default, and 'context' disambiguates. Examples like 'Pipeworx' and 'Boston restaurant' enrich 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 uses specific verbs ('Probe', 'score') and identifies the resource ('LLMs') and output ('visibility (0-100) per model'). It clearly distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on probing LLMs for brand awareness, not general presence scanning.

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

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

Provides clear usage contexts: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' Explicitly states when to use Anthropic (requires _apiKey) and that default is free. Does not list exclusions or alternatives, but the scenarios are well-defined.

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 communicate read-only, open-world, idempotent, and non-destructive behavior. The description adds meaningful behavioral context: it fills arguments automatically, routes to many underlying tools, and returns structured answers with stable pipeworx:// citation URIs. This goes beyond the annotation signals and gives the agent a realistic model of execution.

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

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

The description is front-loaded with the most important instruction and gives a clear data-domain list and examples. It is longer than strictly necessary, with some repetition ('START HERE', 'PREFER OVER WEB SEARCH', 'even if web search could also answer it'), but the length is justified by the routing breadth and the explicit alternative. Overall it remains scannable and actionable.

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 complex routing tool with no output schema, the description gives enough context: it names the input, explains the routing mechanism, and describes the output shape with citation URIs. It also covers the main alternative use case. It does not discuss failure modes, latency, or account limitations beyond a brief 'free account' note for deep_research, but those are secondary to core usage.

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

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

The schema already covers all parameters well, documenting question and its aliases with 100% coverage. The description adds value by embedding concrete example queries and clarifying that the input is a natural-language question about current or historical data. It also reinforces that any of the aliases are acceptable because the question field itself is the single critical 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 states a specific verb and resource: it routes a natural-language question to one of 5,798 tools across 1,517 verified sources and returns a cited structured answer. It clearly positions the tool as a broad factual-answer dispatcher and distinguishes it from web search and from deep_research. The examples further ground what the tool actually does.

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

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

The description gives explicit when-to-use guidance: prefer over web search for factual questions, use for 'what is', 'look up', 'get the latest', 'current', etc., and start here for most questions. It also names one clear alternative, deep_research, for broad multi-part questions. However, it does not explicitly contrast with sibling tools like ask_pipeworx_beta or ask_pipeworx_grounded, so it is not a perfect routing guide.

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?

It discloses the beta nature, the current lack of an active candidate, that it is a full working router with no fallback, and that results are compared to the stable router. This adds meaningful context beyond the readOnly and idempotent annotations, especially the experimental-status and live-routing behavior.

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

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

The description is longer than minimal but every sentence contributes: identity, candidate state, usage intent, and no-fallback clarification. There is some repetition of 'ask_pipeworx', but it is used deliberately to reinforce the relationship with the stable sibling.

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 router-style tool with one required string parameter and no output schema, the description provides sufficient context: same response shape as ask_pipeworx, candidate status, and current equivalence to the stable version. The only mild gap is not clarifying whether comparison to the stable router still happens when no candidate is active, but this is minor.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for 'question'. The description adds no new parameter-level semantics beyond saying the tool accepts the same arguments as ask_pipeworx, so the baseline of 3 applies.

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

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

The description clearly states what the tool is: a beta version of ask_pipeworx acting as the same universal router with candidate routing improvements. It distinguishes itself from the stable ask_pipeworx by labeling itself as the experimental edge and explicitly noting it currently matches ask_pipeworx exactly.

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.' It also explains the evaluation context against the stable router, making the intended use clear. It does not explicitly list when not to use it, but the beta/stable distinction implies the exclusion.

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

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

The description discloses rich behavioral traits beyond the readOnly/openWorld/idempotent annotations: it always returns a specific shape with verbatim evidence, and refuses explicitly with enumerated refusal_reason values (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). It also reveals the extra LLM call cost and the 'ONLY what the tool result contains' extraction constraint. No contradiction with annotations.

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

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

The description is dense but front-loaded with the core purpose, and every sentence carries distinct value: mechanism, return shape, refusal behavior, usage timing, and cost tradeoff. The inline enumeration of refusal reasons is lengthy but earns its place given there is no output schema to carry that contract.

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

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

Despite having no output schema, the description fully specifies the success and failure return contracts, all refusal reasons, cost implications, routing scope, and evidence format. For a complex tool backed by thousands of sources, an agent has everything needed to invoke it correctly and interpret its results without guessing.

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 single semantic parameter 'question' is fully documented along with all six aliases (q, text, input, query, prompt). The description adds context about how the question gets routed across tools, but no syntax or formatting requirements beyond the schema, so the baseline 3 for full schema coverage is appropriate.

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

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

The description opens with a specific verb+resource: 'Hallucination-resistant answer mode for high-stakes reads' — a grounded Q&A tool that routes through 5,798 tools and extracts answers only from tool results. It clearly differentiates from siblings by stating 'Same routing as ask_pipeworx' while adding the extraction/evidence contract that makes it distinct from both ask_pipeworx and ask_pipeworx_beta.

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

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

Explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on... must not invent facts (financial verdicts, legal claims, medical lookups, public statements)'. It also gives the exclusion condition — 'prefer ask_pipeworx for casual lookups' — naming the alternative directly and supplying the cost-based reason for the choice.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, providing a safe profile. The description adds extensive behavioral details: resolution process, fan-out logic, response shapes, market match confidence, parent event extraction, news fields, safety measures (low-confidence short-circuit, closed market handling), spread warnings, and cancellation rule parsing. This goes far 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 comprehensive but very long (over 500 words), which reduces conciseness. It front-loads the purpose but then includes extensive details about classifiers, examples, response shapes, and safety checks. While all information is valuable, it could be more structured or condensed without losing essential guidance.

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

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

Given the tool's complexity (multiple fan-out categories, response fields, safety checks), the description is exceptionally complete. It covers market match confidence, parent event extraction, news fields with fallback handling, resolution rule risk, and blocking conditions. No output schema exists, so the description fully explains return values and edge cases.

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

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

All three parameters are described in the schema with 100% coverage. The description adds significant value by explaining the 'depth' parameter (quick vs thorough), the 'include_raw' parameter (summarized vs full payloads), and the 'market' parameter with format examples (slug, URL, question text). This provides agents with clear 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 the tool's purpose: researching a Polymarket bet by pulling Pipeworx data. It specifies acceptable inputs (slug, URL, question text) and explicitly lists use cases ('should I bet on X', 'what does the data say about Y'). This distinguishes it from sibling tools like deep_research or validate_claim, which are not mentioned but the focus on Polymarket bets sets it apart.

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 and examples of fan-out for different bet categories, giving agents clear context for when to invoke this tool. However, it does not explicitly state when not to use it or contrast with alternatives like deep_research, which slightly reduces the score.

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. The description adds rich behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and inclusion of 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?

The description is well-structured: use-case examples first, then behavior details, then return format. It is informative but could be slightly more concise; however, every sentence earns its place and is front-loaded with key phrases.

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 covers what is returned (paired data + citation URIs), input constraints, behavior for both entity types, and sorting. All critical aspects for using this comparison tool are addressed, making it complete for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances both parameters: for 'type', it explains what data each enum value retrieves; for 'values', it provides examples, format guidance (tickers/CIKs vs names), and quantity constraints (2–5). This adds meaning beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2–5 companies or drugs. It provides specific example queries ('compare X and Y', 'which is bigger') and distinguishes it from sequential lookups. The verb 'compare' and resource 'entities' are specific and unambiguous.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It gives concrete advice on when to use this tool and quantifies the benefit (replaces 8–15 lookups). It also implies alternatives (entity_profile for single entities).

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 read-only/idempotent annotations by disclosing account and paid-tier requirements, parallel decomposition into 5,798 tools, latency expectations, the findings packet structure, gaps[] for unanswered facets, never-invented behavior, contradictions[], citation_uri fetchability, and semantic excerpting of large records. No contradiction with annotations exists.

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 it is dense and organized around operational facts an agent needs: prerequisites, alternative tool, behavior, output packet, depth semantics, and latency. It front-loads the account requirement and core purpose before diving into details, and nearly every sentence carries unique information for this complex tool.

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

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

Given that there is no output schema, the description thoroughly covers what the agent will receive: verbatim evidence, confidence, source, fetched_at, citation_uri, gaps, and contradictions. It also covers prerequisites, latency, depth behavior, and how citations are made resolvable, so the agent is well equipped to invoke the tool 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?

The input schema already describes both parameters well, so the baseline is 3. The description adds meaningful semantic context beyond the schema by giving example question shapes, explicitly ruling out single lookups, and elaborating how depth levels translate into hops, gap recovery, contradiction scans, and latency.

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

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

The description states a specific verb and resource: grounded multi-source research across Pipeworx's structured data sources, explicitly distinguished from open-web search and from ask_pipeworx. It also names the intended use case (broad/multi-part questions) and provides concrete examples, making the tool's identity unmistakable.

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

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

The description gives explicit when-to-use guidance: best for broad/multi-part research over structured data, and explicitly routes users to ask_pipeworx for single lookups or when not signed in. It also explains depth-level selection and pitchses the account requirement, so an agent can decide between this tool and siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds useful behavioral context about returning top-N tools with full schemas and examples, consistent with annotations. No contradictions.

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

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

The description is well-structured, front-loads the main action, and each sentence serves a purpose: what, when, what returns, when to call. No unnecessary words.

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

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

For a simple discovery tool with no output schema and mostly aliased parameters, the description provides full context: purpose, usage, return format, and call order. 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 description coverage is 100%, so the baseline is 3. The description adds minimal extra meaning beyond listing example queries and alias names, which is helpful but not transformative.

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 'find' and resource 'tools', and distinguishes this meta-tool from its many sibling tools that perform specific tasks. The purpose is immediately obvious.

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

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

Explicit guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available' provides clear context and triggers for use.

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

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

The description adds substantial behavioral transparency beyond the annotations: it explains the parallel fan-out across sources, soft-failure of the USPTO PatentsView API, the expected-empty fda_products case, the meaning of sources_used/sources_failed, private-company resolved:false behavior, and source fallback order. The readOnly and idempotent annotations are consistent with this detail.

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 appropriately front-loaded with example queries and the core 'full cross-source profile in ONE parallel call' message. The dense enumeration of output sections is warranted given the tool's complexity, though some phrasing duplicates the schema and could be tightened.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: it enumerates each output field, source-specific caveats, failure semantics, and edge cases like private companies and empty sections. This is complete enough for an agent to invoke the tool and interpret its response correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mostly repeats parameter guidance already in the schema (ticker, zero-padded CIK, company name, interchangeable type), though it adds evaluative examples and a note about private-company resolution that slightly reinforces parameter meaning.

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

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

The description clearly states a specific verb ('profile'/'research'/'brief') and resource (US public company), with a detailed list of cross-source data and example queries. It does not name a specific sibling tool to differentiate from, but the phrase 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' conveys the intended 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?

The description gives explicit guidance to prefer this tool over chaining single-pack lookups when a holistic view is requested, and supplies example user phrasings. It lacks explicit when-not-to-use conditions or named alternatives, but the context is clear enough for an agent to route most entity-profile requests correctly.

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 destructiveHint=true, but the description adds behavioral context (e.g., clearing sensitive data, stale context) that helps justify usage beyond mere deletion.

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

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

Two sentences: first states purpose, second provides usage guidance and pairing suggestion. No redundant words 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 simplicity, the description covers what, when, and how to use. Lacks details on output or confirmation, but for a delete operation this is acceptable.

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

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

Schema coverage is 100% with the single parameter 'key' fully documented. The description does not add further meaning beyond 'by key,' so baseline 3 is appropriate.

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

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

The description explicitly states 'Delete a previously stored memory by key,' using a specific verb and resource. It distinguishes itself from siblings 'remember' and 'recall' by focusing on deletion.

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?

Clear use cases are provided: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also suggests pairing with 'remember' and 'recall.' No explicit when-not-to-use, but adequate for context.

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

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

The description discloses that the tool fetches the page, extracts title/description/key links, and emits markdown, which is behavior beyond annotations. Annotations already indicate it is read-only, idempotent, and non-destructive, so the description adds contextual detail about the external network call and output structure. No mention of rate limits or handling of large pages, but still solid.

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 with a front-loaded main point, followed by a concise process explanation and three bullet-like use cases. Every sentence serves a purpose; no fluff. Ideal length and 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?

Given the tool's simplicity (2 params, no output schema, strong annotations), the description covers the core functionality and output format. It states the output is 'a single text blob ready to drop at site-root/llms.txt'. It lacks mention of potential issues (e.g., only public pages, JavaScript rendering, timeout handling) but is sufficient for an AI agent to understand usage.

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

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

Both parameters have clear schema descriptions (100% coverage). The tool description does not add significant extra meaning beyond what the schema already provides—it restates the purpose of url and max_links without additional formatting or behavioral nuance. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates an llms.txt file for a URL, specifying the process (fetch, extract, emit) and the output format. It provides use cases but does not explicitly differentiate from sibling tools like scan_competitor_ai_presence, which might also involve AI indexing.

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

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

The description lists three typical use cases ('getting a client's site indexed...', 'drafting for your own project', 'auditing competitor'), giving clear context for when to use it. However, it does not explain when not to use it (e.g., for sites behind logins) 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 already declare readOnlyHint, idempotentHint, destructiveHint. Description adds which fields are returned and default behavior, no contradiction.

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

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

Two concise sentences, front-loaded with key action and details, no waste.

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

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

Simple tool with one optional parameter and no output schema; description provides all necessary context.

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

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

Schema covers 100% of parameter. Description adds no extra meaning beyond schema, baseline score.

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

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

Clear verb ('List') and resource ('subscriptions'). Distinguishes from siblings '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?

Provides explicit usage advice: 'review what you're monitoring before adding more or to find an id to cancel.' Lacks when-not-to-use, but sufficient 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?

Discloses several non-obvious behaviors beyond the neutral annotations: rate-limited to 5 per identifier per day, does not count against tool-call quota, filing without an account returns a claim_token, and the token can be used later to check status. Also warns not to paste the end-user's prompt. This is thorough behavioral disclosure.

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

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

The description is one well-organized paragraph with a clear first sentence and logical progression from purpose to constraints. While longer than strictly minimal, every sentence contributes meaningful detail (e.g., rate limits, token usage, source scoping). It could be tightened slightly but is appropriately sized for the tool's complexity.

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

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

Despite having no output schema, the description fully explains expected behavior: what happens when filing with no account (returns claim_token), how to retrieve status later, daily rate limits, and quota impact. It covers all relevant scenarios for a feedback tool with four optional parameters, making it 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, so baseline is 3. The description adds workflow context not in the schema, such as explaining the claim_token round-trip and emphasizing the need for tool-specific context. This extra value lifts it above baseline but doesn't reinvent parameter documentation.

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

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

The description opens with a clear, specific statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates the exact types of feedback (bug, feature, data_gap, praise) and explicitly distinguishes from siblings by scoping only to Pipeworx tools and instructing to file elsewhere for 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?

Provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog...' Also gives a strong exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This clearly prevents misuse and directs to 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?

Adds rich behavioral context beyond annotations: data source (CF analytics-engine), privacy (no PII), caching (5min-1h). No contradictions with annotations (readOnlyHint, openWorldHint, idempotentHint all align).

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

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

Concise yet comprehensive: one sentence for output, a bulleted list for use cases, and a final technical note. Every sentence provides value, no filler.

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

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

For a simple list tool with one parameter and clear annotations, the description fully covers purpose, usage, behavior, output, and caching. No gaps.

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

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

Single parameter has 100% schema coverage. Description adds meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand' — this is valuable guidance beyond the enum.

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

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

Description clearly states verb 'Returns' and resource 'top tools, top packs, total call volume' over configurable windows. Distinguishes from siblings by emphasizing trending/aggregation nature and self-contained signal.

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 lists three concrete use cases (discovering hot sources, confirming canonical tool, checking alignment). Implicitly differentiates from sibling query tools. No explicit when-not-to-use but context is provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds significant behavioral context: it explains the semantic anchor (Jaccard similarity), partition filter (placeholder slugs), fill check (CLOB depth pricing), and when not to trade (realizable_edge_pp ≤ 0). 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?

The description is dense but well-structured: it front-loads the purpose, then explains modes, then dives into technical details. Every sentence adds value. A minor improvement could be clearer separation of sections, but overall it is efficient and 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?

Despite lacking an output schema, the description explains the response structure (opportunities array with fields, partition_check object in event mode, fill check details). It covers edge cases (placeholders filtered, thin legs) and provides enough context for an agent to interpret results. The complexity of the tool is high, and the description 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?

Both parameters have schema descriptions, but the tool description adds substantial meaning: examples of event slugs, acceptance of full URLs, example seed questions for topic, and behavioral differences between modes. This significantly enhances the agent's 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 the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes three modes: no args (trending scan), event (specific market), and topic (cross-event scan). The verb 'find' and resource 'arbitrage opportunities' are explicit, and it differentiates from sibling tools like polymarket_fill_risk.

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

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

The description provides explicit guidance on when to use each parameter: no args for trending scan, event for specific market, topic for cross-event scan. It notes that cross-event mode catches patterns single-event misses. It also mentions a sibling tool for custom sizing (polymarket_fill_risk). However, it does not explicitly list when not to use this tool or provide exclusions.

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

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

The description provides extensive behavioral details beyond the annotations: it explains model families, segment definitions, edge calculation, slippage, caching at KV level, and diagnostics for empty segments. This fully compensates for the lack of detailed annotation information.

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 structured with clear sections, but it is verbose with many details (e.g., specific model alphas, gate parameters). It could be more concise while retaining key information for agent consumption.

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, multiple segments, caching, diagnostics), the description is remarkably complete. It explains return structure, edge calculation, knob usage, and diagnostic counters, leaving no critical aspect uncovered.

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

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

The input schema already covers 100% of parameters with descriptions, so the baseline is 3. The description adds macro context about 'TRADEABLE-EDGE KNOBS' but does not significantly enhance parameter 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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, using a specific verb and resource. However, it does not differentiate from sibling tools like 'polymarket_arbitrage' or 'polymarket_edge_tracker', which may have overlapping functionality.

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

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

The description states the tool is 'Built for 'what should I bet on today'' and mentions Fed bets are excluded from ranking, providing context. However, it does not explicitly state when not to use this tool or list alternative tools for related tasks.

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

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

Annotations indicate read-only, idempotent, and non-destructive behavior. The description adds substantial behavioral details: response structure (tracked, expired, snapshot_dates), meaning of decay fields, limits (60-day TTL), and that gaps occur when no scanning happened. 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 longer but well-structured, starting with the core question and then detailing response fields. Each sentence adds value, though it could be slightly more concise without losing information.

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

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

Given no output schema, the description fully explains the response (tracked, expired, snapshot_dates) and limitations (TTL, snapshot start). It covers all necessary aspects for an agent to understand output and 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%. The description repeats defaults and ranges for 'days' and 'window', adding clarity that 'days' is clamped 2-30 and 'window' defaults to '1wk'. This reinforces schema details, providing minor additional value.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' and the specific question it answers: 'how long has this edge existed and is it shrinking?'. It uniquely identifies this tool among siblings like 'polymarket_edges' by focusing on temporal dynamics.

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 strong usage context, explaining when persistence matters (fresh vs old wide edges) and how to interpret results (e.g., negative edge_pp_net indicates SELL YES). It does not explicitly state when not to use this tool or name alternatives, but the context is sufficiently clear.

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

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

Annotations already mark readOnlyHint, idempotentHint, and not destructive. Description adds rich behavioral context: walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), warns about partial fills and unhedged directional risk. 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 thorough and well-structured into sections, but somewhat verbose. Every sentence is earned given the complexity, but could be tightened slightly 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?

Despite no output schema, the description fully lists return fields for both modes, explains the verdict, and covers risk warnings. Given tool complexity and sibling context, it provides everything needed for correct invocation.

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

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

While input schema has 100% description coverage, the description adds significant meaning: explains default behavior for side, size_usd interpretation differs per mode, and the mutual exclusivity of market vs event. This elevates 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 the tool's function: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes with explicit verb+resource, and differentiates from siblings like polymarket_arbitrage and polymarket_edges by specifying usage before acting on their signals.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also implies when not needed (small trades) and gives requirements (one of market or event).

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

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

Beyond the annotations' readOnly/idempotent hints, the description discloses many non-obvious behaviors: pairing_unverified is always set, unknown metric/subtype legs are never paired, temporal_alignment null means 'could not be computed,' and spreads are gross because Kalshi fees are not modeled. 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?

The description is front-loaded with the core purpose and logically progresses from modes to response shape to safety codes. It is dense and repeats a few phrases, but for the tool's complexity it is close to appropriately sized; tighter formatting would improve scannability.

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

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

With no output schema, the description compensates thoroughly by specifying the response shape, compatibility code meanings, skipped-leg behavior, alignment semantics, and the fees_note caveat. It covers enough edge cases that an agent can call the tool and interpret its results safely.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine value by explaining that topic auto-fetches matching events on both venues while explicit params create a custom pairing. It also clarifies that both modes run the same token-overlap matcher, which is not obvious from the schema alone.

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

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

The opening sentence, 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' states exactly what the tool computes and differentiates it from sibling venue tools. The two-mode explanation (topic shortcuts vs explicit ticker/slug) further clarifies both the purpose and operational 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?

The description gives clear context for when to use the tool: 'when the bet shapes are equivalent that delta is a real signal' and warns that 'pre-mapped ≠ tradeable.' It explains how to choose between topic and explicit modes, but does not explicitly compare against sibling tools or state when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by specifying the exact data fields returned (contact info, email, phone, account balance) and the retrieval method (by customer ID), providing context beyond the annotations.

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

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

The description is a single sentence that conveys all essential information without any fluff. Every word serves a purpose, making it highly efficient.

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

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

Given the presence of an output schema and simple parameter, the description covers all needed context: what the tool does, what it includes, and how to call it. No gaps for a read-only retrieval tool.

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

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

The single parameter 'id' is fully described in the schema as 'QuickBooks Customer ID'. The tool description only echoes 'by customer ID', adding no new semantics. With 100% schema description coverage, the description adds minimal value beyond the schema.

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

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

The description clearly states the tool retrieves a customer's complete profile with specific fields (contact info, email, phone, account balance) by customer ID. This distinguishes it from sibling tools like qb_get_invoice or qb_list_invoices, which serve different purposes.

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

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

The description implies usage when a full customer profile is needed by ID, but does not explicitly state when to use this tool versus alternatives like qb_query or qb_list_accounts. No exclusions or prerequisites are mentioned.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds value by specifying what data the response includes (line items, amounts, taxes, payment history), which goes beyond annotations and helps the agent understand the tool's output.

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 sentence that is concise and front-loaded with the key information. There is no wasted text.

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 that there is an output schema (context signal) and the tool is simple (one required parameter), the description provides enough context about what is retrieved. It does not need to explain return values because the output schema covers that.

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

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

Schema coverage is 100% and the parameter 'id' is documented in the schema. The tool description does not add additional semantic meaning beyond the schema's description, so baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves a complete invoice by ID, with a specific verb 'retrieve' and resource 'invoice'. It distinguishes from sibling tools like qb_list_invoices (which lists invoices) and qb_get_customer (which gets a different 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?

The description does not provide explicit guidance on when to use this tool versus alternatives or when not to use it. It implies use for single invoice retrieval, but lacks exclusions or context for comparison with qb_query or qb_list_invoices.

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 destructiveHint=false. The description adds value by specifying the returned fields (account names, types, balances, classifications), which helps the agent understand what data to expect. 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?

A single sentence that efficiently conveys purpose and key data fields with no wasted words. Perfectly front-loaded.

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

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

Given the tool's simplicity (one optional param, no nested objects) and the presence of an output schema, the description adequately covers purpose and output. It could mention pagination or how to get all accounts, but it is generally complete for a read-only list tool.

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

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

Schema coverage is 100% with a good description of the max_results parameter (default and max). The description does not add additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description uses a specific verb 'Get' and clearly identifies the resource 'chart of accounts', listing key data fields (names, types, balances, classifications). This distinguishes it from sibling tools like qb_query which are more generic.

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 its use for retrieving chart of accounts but offers no explicit guidance on when to prefer this over alternatives (e.g., qb_query). No exclusions or when-not-to-use advice is provided.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds value by specifying returned fields and pagination parameters, consistent with annotations.

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

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

Two sentences, no wasted words. First sentence states purpose and output, second provides alternative. Highly efficient.

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

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

Description covers purpose, output fields, and sibling alternative. Schema covers parameters and pagination. Near complete for a simple list tool.

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

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

Schema coverage is 100% with clear parameter descriptions. Description does not add new parameter context but is sufficient. 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 verb 'Get', resource 'invoices', and lists specific fields returned (number, customer, amount, due date, payment status). It also distinguishes from sibling qb_get_invoice for full details.

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 recommends qb_get_invoice for full line-item details, guiding selection between related tools. Does not explicitly state when not to use, but context is clear.

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

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

Annotations already state readOnlyHint, idempotentHint, destructiveHint. Description adds that it returns raw API response and uses QBO query language, but doesn't elaborate on potential limits, pagination, or error behavior. Adequate but minimal added value.

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

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

Single sentence with essential information front-loaded. Example included inline. No redundant words.

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

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

Given the simple one-parameter tool, rich annotations, and presence of output schema (not shown but signaled), the description sufficiently covers purpose, usage, and behavior. No gaps identified.

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 the single parameter with a description. Description adds value by providing examples of valid queries and explaining the query syntax, which goes beyond the schema's description.

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

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

Clearly states the tool executes a QuickBooks SQL-like query against any entity type, with an example. Distinguishes from sibling tools like qb_get_customer and qb_list_accounts which are opinionated retrieval 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?

Implies general use for querying any entity, but doesn't explicitly contrast with specific getter/list tools or provide guidance on when not to use it. Could mention that for single records the dedicated getter tools may be more appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds scoping by identifier and the pair-with pattern, which provides useful 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 three sentences, front-loaded with the core action. Every sentence adds distinct value: retrieval vs listing, usage guidance, and scoping.

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 covers what happens for both key provided and omitted. It provides sufficient context for an agent to use the tool correctly.

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

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

Schema coverage is 100% and describes the key parameter. The description adds the behavior of omitting the key to list all, which is not explicit in the schema alone.

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

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

The description clearly states the tool's purpose: retrieving a value by key or listing all keys when omitted. It distinguishes itself from sibling tools (remember, forget) by explicitly naming 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?

The description explains when to use the tool (look up stored context without re-deriving) and pairs it with remember/forget. It could explicitly state when not to use (e.g., for saving), but the context is clear.

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

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

Discloses return structure with fields, explains the side effect of mark_read on read state, and notes the feed availability via a separate GET endpoint. Adds significant context beyond the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations, with no contradictions.

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

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

Single compact paragraph that front-loads the purpose and efficiently covers all key aspects without redundancy. Every sentence adds value, making it easy to scan.

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

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

With 5 optional parameters and no output schema, the description adequately covers return fields, filter usage, state management via mark_read, polling guidance, and an alternative access method. Nothing essential is missing.

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

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

Schema coverage is 100%, but the description enhances each parameter: explains the filtering role of 'type', the ISO timestamp format for 'since', the state-changing behavior of 'mark_read', and the null-check logic for 'unread_only'. Goes well beyond baseline.

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

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

Clearly states the tool pulls fired events from subscription feed, specifies returned fields (source, citation_uri, raw payload), and covers filtering by type and time. Distinguishes itself from sibling tools that likely handle different actions like listing subscriptions or searching.

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 polling works fine and provides an alternative REST endpoint for scripts/dashboards. Explains that setting mark_read:true affects subsequent calls, guiding appropriate usage patterns.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds context: makes one parallel call, fans out to specific sources, describes fallback behavior, and explains soft-fail for patents.

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?

A single dense paragraph, well-structured with examples upfront. No redundancy, but could be slightly more concise. Every sentence earns its place.

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

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

No output schema, but description fully explains return structure (changes grouped by source, total_changes count, citation URIs). Covers all input parameters and sources.

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

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

Schema coverage is 100%, but description adds meaning: explains 'since' formats with examples, clarifies 'value' accepts ticker or CIK, and notes only 'company' type supported.

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

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

The description clearly states it provides a change feed for a company in the last N days, fanning out to multiple sources. It specifies the verb (get changes) and resource (company changes), and differentiates from sibling '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 lists query examples ('What's new with X', 'latest on Y') and instructs when to use 'entity_profile' instead. Also explains fallback logic (GDELT→GNews) and parameter usage.

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

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

Description adds behavioral details beyond annotations: persistent memory for authenticated users, 24-hour retention for anonymous sessions. No contradiction with annotations.

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

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

Two efficient sentences with no wasted words. Purpose is front-loaded, and all information is immediately useful.

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 covers storage behavior, scoping, persistence, and pairing with recall/forget. Fully adequate given the 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 covers both parameters (100%), and description adds meaningful examples (keys like subject_property, target_ticker) that help the agent select appropriate values.

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 saves data for reuse across conversations/sessions, specifies key-value pair storage scoped by identifier, and distinguishes itself from sibling tools like recall and forget.

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

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

The description explicitly says when to use it (discover something worth carrying forward) and pairs with recall/forget, but lacks explicit 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?

Despite annotations declaring readOnlyHint, openWorldHint, and idempotentHint, the description adds substantial behavioral context: it cascades through multiple endpoints internally, asserts nothing when multiple FIGI candidates exist, explicitly reports unresolved identifiers, degrades gracefully when external sources fail, and labels identifiers with their provenance. This goes far beyond what the annotations capture.

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 an extremely long and dense wall of text with no bullet points, headings, or clear hierarchical structure. While every sentence carries information, the lack of formatting and the sheer volume make it difficult to parse quickly. It is under-structured rather than concise, earning a low score on this dimension.

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 complex tool with two entity types, multiple identifier sources, and fallback behaviors, the description covers all necessary runtime aspects: what is returned for each type, how to handle ambiguous matches, behavior on source failures, and the internal cascading mechanism. There is no output schema, so the description correctly takes responsibility for explaining return values and edge cases. Nothing critical is missing.

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

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

The schema already covers both parameters at 100%, including format guidance for 'value'. The description supplements this by noting that 'value' can also accept an ISIN for company type (not mentioned in the schema) and clarifies the exact naming convention for bonds ('never the question's full noun phrase'), adding meaning beyond the schema. This justifies a rating above the baseline of 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 states a specific verb ('resolve') and resource ('a user-spoken NAME to the canonical/official identifiers') and clearly distinguishes itself from sibling tools by positioning as a prerequisite for tools that require IDs. It provides multiple example queries that map directly to this tool, making its purpose unambiguous to an agent.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID' and gives numerous examples of when this applies, including detailed handling for companies, drugs, and bonds. However, it does not explicitly name alternative tools or state when NOT to use it (e.g., when an ID is already known). This is a minor omission given the clarity of the primary condition.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details: it probes each entity with `ai_visibility_check`, ranks by score, and returns a ranked list with score, confidence, and signal density. No contradictions.

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

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

The description is concise with two sentences, front-loading the main action. It avoids verbosity, though it could be slightly more structured (e.g., bullet points for output 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 the tool's complexity (multi-entity comparison, no output schema), the description provides key return fields (score, confidence, signal density) and the ranking logic. It mentions the first entity as the subject. However, it does not explain 'signal density' or the exact ranking algorithm.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds marginal value: it clarifies that the first entity in 'entities' is treated as the subject for narrative. No further elaboration on models, _apiKey, or context beyond what 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's purpose: compare AI visibility across multiple entities side-by-side. It specifies the action (compare, probe, rank), resource (AI visibility), and distinguishes it from siblings like `ai_visibility_check` (single entity) and `compare_entities` (generic).

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 for competitive AI-marketing audits, giving a concrete use case. It implies when to use (comparing multiple entities) and references the alternative `ai_visibility_check` for single entities. However, it does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds critical behavioral context: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timeouts. No contradiction with annotations.

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

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

The description is comprehensive but slightly lengthy. It is well-structured with the main purpose front-loaded, followed by return values, ecosystem notes, and performance caveats. Each sentence adds value, but could be tightened slightly.

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 return format: summary block fields, per-advisory details, links, and alternative versions. It also covers partial failure and performance behavior. The tool is complex but the description leaves no major gaps.

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

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

Schema coverage is 100% with descriptions for both parameters (package name with scoped support, version with default). The description does not add significant new meaning beyond stating that version defaults to latest. Baseline 3 is appropriate.

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

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

The description clearly states the tool as a composite check for adding npm packages, covering license, advisories, size, etc. It specifies the verb 'scan' and resource 'dependency', and distinguishes from siblings by focusing on npm and using multiple sources.

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

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

The description explicitly says when to use: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also clarifies ecosystem boundaries: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This provides clear guidance on 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?

Beyond annotations (readOnlyHint, idempotentHint), the description adds rich behavioral context: embedding model (BGE-base-en), search technique (cosine over 500-char overlapping windows), character limit (200K) with truncation flag, and output format (passages with offsets and scores). 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 well-structured sentences with bold emphasis on key terms. Front-loaded with the core action, followed by use cases, usage advice, technical details, and constraints. Every sentence contributes meaning.

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

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

Despite no output schema, the description fully explains what is returned (top-N passages with character offsets and similarity scores) and covers the input constraints (200K char limit). All essential information is present for correct invocation.

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

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

Schema coverage is 100% with descriptions. The description reinforces each parameter's meaning, provides concrete examples for 'query', and clarifies the default and range for 'limit'. Adds value beyond the schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific examples (SEC 10-K, article, long tool result). It distinguishes from siblings like ask_pipeworx_grounded by specifying that search_within operates on already-fetched text.

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

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

Explicitly tells when to use: 'when the record is too big to cram into the prompt' and explains benefits (saves context, returns relevant passages with offsets for verification). Mentions pairing with ask_pipeworx_grounded, providing clear guidance on workflow.

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

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

Annotations indicate readOnlyHint false, openWorldHint true, idempotentHint true, destructiveHint false. The description adds context: requires OAuth, always-on feed, optional email/SMS/webhook with specific constraints, but does not address idempotency (repeated calls likely create duplicates). The description enriches 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 relatively long but well-structured: purpose first, then auth, then types, then delivery options. Each sentence adds value; no redundancy. Could be slightly tighter, but remains clear and organized.

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 mentions 'Returns the new subscription id', which is sufficient but minimal. The input side is thoroughly covered given complexity. Missing details on response structure or error handling, but adequate for selection/invocation.

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

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

Schema coverage is 100%, and the description adds significant meaning: examples for each type, delivery channel specifics (e.g., SMS 10/day cap, webhook signing secret, auto-disable). This goes well beyond the schema's field 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 creates a proactive monitoring subscription and returns a subscription ID. It distinguishes from related tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and listing specific subscription types.

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

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

The description explains when to use (proactive monitoring), prerequisites (Pipeworx OAuth account), and limitations (SMS cap, phone verification). It does not explicitly state when not to use or compare with alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds operational behavior: returns 'category-bucketed example questions' with exact tool+argument shapes, and explains calling with/without `topic`. No contradictions.

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

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

Description is front-loaded with common user queries and efficiently covers purpose, usage, and format. Slightly verbose but each sentence adds value.

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

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

For an onboarding tool, description is complete: explains what it does, when to use, how to call, what it returns, and its relationship to other tools. No output schema needed.

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 describes `topic` with categories. Description adds little beyond listing categories; baseline 3 is appropriate.

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

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

The description clearly states the tool returns category-bucketed example questions with tool+argument shapes. It explicitly positions itself as the onboarding entry point for new agents and distinguishes from siblings by saying 'Use this FIRST'.

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: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also explains when to use the `topic` parameter for narrowing focus.

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

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

Description discloses behavioral traits beyond annotations: ownership enforcement, deactivation (not deletion), and retention of historical events via recent_alerts. No contradiction with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true).

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, no wasted words. Front-loaded with action, then key behavioral details. Every sentence earns its place.

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

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

Given the tool's simplicity (one param, no output schema), the description covers essential context: cancellation effect, ownership, and link to sibling tool recent_alerts. Slight omission of return format, but acceptable.

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

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

Schema coverage is 100% with a clear schema description for 'id' (uuid from subscribe). The description adds minimal value beyond schema, only referencing 'by id' and ownership, which is already implied. 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 uses a specific verb ('Cancel') and resource ('subscription') immediately, clearly stating the action. It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by specifying cancellation.

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

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

The description explicitly states ownership enforcement ('you can only cancel your own subscriptions'), guiding the agent on when the tool applies. It does not list alternatives but provides sufficient context for correct invocation.

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/openWorld/idempotent annotations, the description adds crucial behavioral details: the two routing paths (SEC EDGAR vs grounded), the exact verdict enum, the distinction between could_not_verify (check failed, not evidence) and unsupported (no source exists), and the inclusion of verbatim evidence with citations. This is rich context that annotations do not provide and is essential for correct interpretation.

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 but information-dense. It front-loads trigger phrases and the core purpose, then explains the two pipelines, return values, and a critical caveat in a logical order. Every sentence earns its place; the length is justified by the tool's complexity. No unnecessary 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 complexity and the absence of an output schema, the description must explain return values and failure modes on its own. It does so thoroughly: verdict values, citation behavior, reasoning, the could_not_verify vs unsupported distinction, and the fact that it replaces multiple sequential calls. This covers all essential operational 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?

The schema descriptions for 'claim' and 'tolerance_pct' are thorough, covering examples, constraints, and defaults. The tool description does not add meaningful parameter-level semantics beyond what the schema already provides. With 100% schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with trigger phrases ('fact check', 'verify the claim that…'). It distinguishes itself from siblings by focusing on verdict generation and specifying two distinct pipelines (SEC EDGAR for company-financial claims, grounded pipeline for others). This is a specific verb+resource+scope that stands out from related tools like ask_pipeworx.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear when-to-use guidance. It also explains that it replaces 4–6 sequential calls, implying efficiency. However, it does not explicitly mention when not to use it or name alternative tools, stopping short of the full 5-point criteria.

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