Xero

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds valuable context: default model is free, Anthropic requires user's API key, and returns per-model details including raw response. No contradictions with annotations.

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

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

The description is a single paragraph that front-loads the main purpose and quickly breaks down when to use each model. It is dense but efficient; minor structural improvement (e.g., bullet points) could enhance readability without adding length.

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 compensates by explicitly listing the return structure (score, confidence, signals, raw_response per model plus combined view). This provides sufficient completeness for a simple tool with only 4 parameters.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds meaning beyond schema: explains that _apiKey enables Anthropic probes and context helps disambiguate entities. This enhances understanding of parameter usage.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about a business/brand/product/topic and scoring visibility. It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on visibility scoring and supporting multiple models.

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

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

The description provides clear use cases (AI-marketing audits, pre-launch checks, competitive monitoring) and explains when to use the Anthropic model (requires BYO key). It lacks explicit when-not-to-use or alternative tool references but is still informative.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: it routes to 5,529 tools, fills arguments, returns stable pipeworx:// citation URIs, is 'one fast call', and works on every tier. It does not contradict annotations, though it omits failure modes or rate limits, which are not essential given the annotation coverage.

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

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

The description is lengthy (~200 words) but front-loaded with the key instruction (PREFER OVER WEB SEARCH) and every section adds value: domain list, behavior, examples, default positioning, and alternatives. It could be trimmed slightly but is well-structured and not redundant.

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

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

No output schema exists, but the description explains what it returns (structured answer with citation URIs). It covers purpose, usage, examples, alternatives, and behavioral context. For a complex routing tool with many siblings, this description is highly complete.

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

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

Schema coverage is 100%, with the question parameter and its aliases (query, q, prompt, text, input) fully documented. The description adds real-world examples of questions but no new format details. The 'fills arguments' mention refers to internal routing, not user parameters. 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 says it is preferred over web search for questions about current/historical data, listing many domains, and explains it routes questions to 5,529 tools and returns structured answers with citation URIs. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making its unique purpose clear.

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

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

It provides explicit when-to-use guidance: 'Use whenever the user asks...' with trigger phrases and examples, and clearly states when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions). It also notes it is the default entry point and works on every tier.

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=true, openWorld=true, idempotent=true), the description adds crucial behavioral context: it is a full working router, not a fallback; it may have candidate routing improvements under test; and currently matches the stable version. This transparency about its experimental state goes far beyond the structured hints.

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

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

The description is four sentences long, each adding meaningful information (beta status, current state, usage instruction, fallback reassurance). It's slightly verbose but well-structured and front-loaded with the core purpose.

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

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

Given the tool's experimental complexity, the description is highly complete: it explains the relationship to ask_pipeworx, current behavior, how to use it, and that it's a fully functional router. It references the same response shape as ask_pipeworx, which, while not detailed, is sufficient given the 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?

The input schema has 100% coverage for all parameters, each clearly described as aliases for 'question'. The description adds no parameter-level detail, but with full schema coverage, the 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 this is a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. This specific verb+resource scope distinguishes it from the sibling ask_pipeworx and clarifies its experimental nature.

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 it exactly like ask_pipeworx when you want the newest routing,' providing clear when-to-use guidance. It also notes that currently no candidate is active so it matches ask_pipeworx exactly. It lacks explicit exclusions for when not to use it, but the context is clear enough.

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

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

The description discloses extensive behavioral details beyond the annotations: it returns a structured response with evidence, confidence, source, and fetched_at, and provides explicit refusal reasons. It explains the extraction constraint and the added cost, none of which annotations convey. No contradiction with readOnlyHint/openWorldHint.

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

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

The description is well-structured and each sentence earns its place: it opens with the core value proposition, then details the mechanism, return/refusal format, and ends with usage guidance and cost trade-off. It is information-dense but not bloated.

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

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

Despite lacking an output schema, the description fully specifies the success response fields and refusal reasons, covering return behavior comprehensively. It also explains when to use the tool and its cost implication, making it complete for the tool's complexity.

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

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

Schema description coverage is 100% and the only meaningful parameter is 'question' with aliases, all documented in the schema. The description adds no additional parameter meaning, so with high 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: a hallucination-resistant answer mode for high-stakes reads. It specifies the exact behavior (routes to tools, fills arguments, fetches data, extracts answer only from tool result) and differentiates it from the sibling ask_pipeworx by emphasizing grounded extraction and explicit refusals.

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

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

Explicit guidance is provided: use when an answer will be quoted, cited, or acted on, and facts must not be invented. It also names the alternative (ask_pipeworx) and explains the trade-off (extra LLM call, prefer for casual lookups), giving clear when-to-use vs when-not-to-use 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?

Beyond annotations (readOnly, idempotent), the description details resolver contracts, short-circuiting on low confidence, closed market handling, wide spread tradeability, and cancellation rule parsing. No contradiction with annotations.

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

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

The description is lengthy but well-structured with clear sections (RESPONSE SHAPES, RESOLVER CONTRACT). It is front-loaded with core purpose. Minor redundancy in parameter descriptions.

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 response structure, edge cases, safety conditions, and resolution rules. It is complete for agent decision-making.

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

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

Schema coverage is 100%, and the description adds minimal additional meaning for parameters like 'depth' and 'include_raw'. The description of 'depth' is redundant with the schema's enum description.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, with specific examples like 'should I bet on X'. It distinguishes from sibling tools like polymarket_edges by focusing on a single bet research vs. edge tracking.

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 use cases ('should I bet on X') but lacks guidance on when not to use or alternatives. Usage is implied through examples rather than explicit conditions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: it handles different entity types, pulls specific metrics from SEC EDGAR/XBRL and FAERS, handles fiscal year anomalies, sorts results by primary metric, and returns citation URIs. No contradiction.

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

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

The description is relatively dense but every sentence adds value. It is front-loaded with trigger phrases and key advice. Slight improvement could be to break into bullet points, but overall effective.

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

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

Given the tool's complexity (two entity types, no output schema), the description covers what data is returned, how results are sorted, citation format, and the efficiency gain. It is complete enough for an AI agent to select and invoke correctly.

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

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

Schema coverage is 100% with descriptions. The description adds practical context for parameter values (e.g., tickers for company, drug names for drug) and explains the data sources. It enhances understanding beyond schema.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It provides specific trigger phrases (e.g., 'Compare X and Y', 'X vs Y') and distinguishes itself from single-entity lookups like entity_profile.

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

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

The description explicitly advises ALWAYS PREFER this tool over sequential single-pack lookups for comparisons, giving clear usage guidance. It does not explicitly state when not to use, but the context is clear.

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

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

The description discloses auth requirements, latency ranges, gaps[] behavior ('never invented'), semantic excerpting, and the hop/citation_uri contract, all beyond the annotations. It also clarifies that 'thorough' requires a paid plan and that standard/thorough include a contradictions[] scan.

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 every sentence adds critical operational detail—auth, comparison, depth semantics, citation guarantees. It front-loads the account requirement and primary use case, then layers deeper behavior, making the length appropriate for a tool with this 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?

With no output schema, the description fully explains the findings packet structure, gaps[], contradictions[], hop field, and citation_uri, and it also covers timing and prerequisites. Given the tool's complexity and the rich sibling context, the description leaves no significant gap for an agent to select and invoke it correctly.

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

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

While the schema already documents both parameters, the description adds crucial semantics: the depth enum's hop behavior (quick=1, standard=gap recovery+contradictions, thorough=iterative follow-up), the cost implications of 'thorough', and guidance that 'question' accepts broad/multi-part queries. This is a significant addition 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 states a specific verb ('research') with a clear resource ('Pipeworx's 1455 STRUCTURED data sources') and explicitly contrasts with open-web search and the ask_pipeworx sibling. It also describes the decomposition and parallel tool routing, making the tool's function 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?

It gives explicit when-to-use ('Best for broad/multi-part questions over structured data') and when-not-to-use ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'), plus the sign-in prerequisite and fallback to ask_pipeworx when not authenticated.

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 that each result includes full input schemas with curated examples ready to call, which enriches understanding of output behavior without contradicting annotations.

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

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

The description is thorough but slightly long; it is well-structured with a clear first sentence, domain list, return format, and usage guidance. Every sentence adds value, though it could be slightly more concise.

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

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

Despite no output schema, the description fully explains what is returned (tool names, descriptions, schemas with examples). For a discovery tool with 6 parameters, all necessary context is provided.

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 schema already documents all parameters and aliases. The description provides example queries and explains the main 'query' parameter's use, adding some value but not significantly beyond the schema.

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

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

The description clearly states it finds tools by describing data/task, enumerates specific domains (SEC filings, FDA drugs, etc.), and explains it returns top-N relevant tools. This distinguishes it from sibling tools which are individual 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?

Explicitly says 'Call this FIRST when you have many tools... want to see the option set (not just one answer),' providing clear when-to-use and implied when-not-to-use (when you already know the tool).

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

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

Beyond annotations (readOnly, idempotent), description adds USPTO patent API sunset details, soft-fail behavior, news fallback, and unsupported name input. No contradiction with annotations.

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

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

Description is front-loaded with example queries and structured into sections. Slightly lengthy but every sentence adds essential behavioral or usage context.

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 details return structure: CIK, filings with URIs, fundamentals (with field names), patents (with sunset), news fallback, LEI. Also notes parallel execution and type limitations.

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

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

Schema coverage is 100%. Description adds examples (AAPL, 0000320193), explains type enum limitation, and clarifies that names require resolve_entity, adding value beyond schema.

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

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

The description clearly states the tool returns a 'full cross-source profile of a US public company' and lists specific data sources and returned fields. It distinguishes from sibling tools like resolve_entity by noting it does not support names.

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 chaining single-pack SEC/XBRL/news lookups' for holistic views and advises using resolve_entity first if only a name is available.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description adds little beyond those. It mentions clearing sensitive data, but no further behavioral traits are disclosed.

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

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

Two sentences, front-loaded with the core action, no wasted words.

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

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

For a simple, one-parameter, no-output-schema tool with informative annotations, the description is complete enough.

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

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

Schema coverage is 100% and the description only repeats the parameter name 'key' without adding 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 'Delete a previously stored memory by key' using a specific verb and resource. It differentiates from sibling tools by explicitly pairing with remember and recall.

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

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

Provides explicit when-to-use scenarios (stale context, task done, clear sensitive data) and mentions pairing with remember and recall, offering guidance on alternatives.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds that it fetches a page, extracts title/description/key links, and outputs a markdown blob, providing behavioral details beyond annotations.

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

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

The description is concise with four sentences, front-loading the purpose and avoiding fluff. Every sentence adds value.

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

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

Given the simple two-parameter schema, rich annotations, and clear output description, the description is complete. It explains input, output, and use cases without needing an output schema.

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

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

The input schema has 100% coverage, and the description does not add significant meaning beyond the schema for the two parameters. The baseline of 3 is appropriate as the schema already provides sufficient semantic information.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and the resource (llms.txt file). It distinguishes from siblings by its unique functionality, as no other sibling tool performs this specific task.

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: getting a client's site indexed, drafting llms.txt, or auditing a competitor. It does not explicitly state when not to use it, but the contexts are clear and helpful.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by detailing the report structure (sections covering revenue, expenses, net profit). No contradictions.

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

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

The description is two sentences, front-loaded with the core purpose, and contains no extraneous information. Every sentence adds value.

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

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

No output schema exists, but the description explains what the report contains (name, date, row sections). Combined with annotations, this is complete enough for a simple read-only report tool.

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

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

Schema coverage is 100%, so parameters are fully documented. The description adds little beyond 'optional date range' which mirrors the schema. No new semantics or formats are introduced, 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 it gets a Profit and Loss (income statement) financial report from Xero, with optional date range. It specifies the structured output (report name, date, row sections covering revenue, expenses, net profit). This is specific and distinguishes from sibling tools, none of which are P&L-related.

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 mentions 'Use for financial reporting and bookkeeping analysis,' providing a clear context for when to use the tool. No alternative tools or exclusions are stated, but siblings are unrelated, so no confusion.

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. Description adds that it returns account details (code, name, type, class, status) but no additional behavioral traits (e.g., pagination, limits) beyond what annotations provide.

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

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

Two succinct sentences: first states action and resource, second states return fields and use case. No redundancy or 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?

Simple tool with one optional parameter, no output schema. Description covers purpose, return fields, and use case completely. No gaps given tool complexity.

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

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

Schema coverage is 100% and description for tenant_id already explains its optionality and source. Description does not add new parameter information, so baseline 3 applies.

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

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

Clearly states verb 'List' and resource 'chart of accounts from a Xero accounting organisation'. Distinguishes from sibling tools like list_contacts, list_invoices by specifying accounts. Also lists return fields.

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

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

Provides context for when to use: 'Use to understand an organisation's general ledger structure for bookkeeping and financial reporting'. Does not explicitly state when not to use or mention alternatives, but sibling list tools imply distinction.

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 specific return fields and filter/pagination support, enhancing transparency beyond annotations.

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

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

Two sentences, front-loaded with purpose and output, then usage and capabilities. No filler or redundancy.

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

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

All parameters documented, return fields described, use cases provided, and annotations cover safety and idempotency. Output schema not needed for such a 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 covers all 3 parameters. Description adds context: ties 'where' to Xero filter expressions, mentions pagination for 'page', and advises using list_organisations for tenant_id.

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 lists contacts (customers and suppliers) from Xero, specifying returned fields. It distinguishes from sibling tools like list_accounts and list_invoices by focusing on contacts.

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 mentions workflows (accounting, bookkeeping, AR/AP) and capabilities (filter expressions, pagination). No explicit alternatives but sibling tools don't offer contact listing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description doesn't need to repeat them. It adds value by specifying that it returns compact summaries and supports filtering and pagination.

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

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

The description is two sentences, front-loaded with the action, and provides all necessary information without unnecessary words.

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

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

Given no output schema, the description adequately explains return value (compact summaries with fields listed), optional tenant_id, and how to get tenant IDs, making it complete for a listing tool.

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

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

Schema coverage is 100%, and the description adds context by mentioning 'Xero filter expressions' and 'pagination', which reinforces the 'where' and 'page' parameters 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 lists invoices and bills from Xero, specifies returned fields (number, type, status, etc.), and mentions specific use cases (bookkeeping, AR/AP review), distinguishing it from sibling tools.

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

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

The description provides clear context on when to use (for reviewing invoices/bills) and mentions support for Xero filter expressions and pagination, but does not explicitly state alternatives or when not to use.

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

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

Annotations already provide readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, which adequately cover safety and idempotency. The description adds context about the output fields and multi-tenant nature but does not contradict annotations.

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

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

Two sentences, no unnecessary words. The first sentence states the action and output, the second provides strategic usage context. 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?

For a parameterless tool with no output schema, the description fully explains what the tool does, what it returns, and how it fits into the workflow. No additional information is 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?

No parameters exist, so schema coverage is 100%. The description adds value by specifying the output contents (tenant id, name, type), which is beyond the schema's empty definition.

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

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

The description clearly states the verb (list), resource (Xero organisations/tenants), and includes specific fields returned (tenant id, name, type). It distinguishes from sibling accounting tools by explaining this is a discovery tool for tenant_id, which other tools require.

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

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

Explicitly says 'use this first' and 'then pass it to the other accounting tools', providing clear when-to-use guidance and context among siblings. It does not elaborate on when not to use, but the purpose is sufficiently specific.

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, but the description adds that it returns specific fields and implies the tool is safe. No contradictions.

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

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

Two sentences, no filler, efficiently communicates purpose, return data, and usage context.

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 lists the return fields, and the single parameter is fully documented. The tool is simple and complete.

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

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

Schema coverage is 100%, so the description adds marginal value, but it reinforces the parameter by stating 'active' subscriptions and linking to the include_inactive parameter implicitly.

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 lists the caller's active subscriptions and specifies the return fields (id, type, params, etc.), making the purpose explicit and distinct from sibling tools like subscribe and unsubscribe.

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

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

Explicitly advises when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context for the agent.

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

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

Beyond the all-false annotations, the description discloses rate limiting (5 per identifier per day), that it is free and doesn't count against tool-call quota, that the team reads digests daily, and how claim_token works for follow-up. No contradiction with annotations.

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

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

The description is long but every sentence earns its place, covering purpose, usage, exclusions, token mechanics, and limits. It is well-structured and front-loaded with the core action first.

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 explains the claim_token return and the overall workflow well. It covers types, context, rate limits, and account behavior. A minor gap is not describing the immediate success response beyond the token, but this is a minor omission.

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

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

Schema covers 100% of parameters, but the description adds practical detail: claim_token usage with a concrete example, message content guidelines, and clarification of the enum types. This goes 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's purpose: sending feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It distinguishes itself from siblings like ask_pipeworx by focusing on reporting issues rather than querying or research.

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

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

It explicitly lists when to use (bug, feature/data_gap, praise) and when not to use (for tools from other MCP servers), with clear guidance to file elsewhere otherwise. It also advises how to formulate feedback (in terms of Pipeworx tools/packs, not user prompts).

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, etc. The description adds valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h), and aggregation method. 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 brief (4 sentences), front-loaded with the main purpose, and every sentence adds value. No fluff or repetition.

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

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

Given the tool's simplicity (one optional param, no output schema), the description covers functionality, use cases, caching, and privacy. It could mention the output format briefly, but overall it is sufficient 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% and the parameter description is already informative. The tool description reiterates window options but adds only minor additional context (e.g., longer windows show steady-state demand). 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 returns top tools, top packs, and total call volume over a recent window. It uses specific verbs and resources, distinguishing it from sibling tools which are mostly query or action tools.

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

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

Three explicit use cases are provided, giving clear context for when to use the tool. However, it does not mention when not to use it or contrast with alternatives like discover_tools.

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

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

Annotations (readOnlyHint, idempotentHint, non-destructive) already indicate safety. The description adds rich behavioral context: describes the scan logic, semantic anchor (Jaccard similarity), partition filter, and fill check. 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?

Every sentence adds value. Front-loaded with purpose and mode overview, then detailed explanations of each mode, semantic anchor, partition filter, and fill check. The structure is logical and well-organized, with no wasted words.

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

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

Given no output schema, the description fully explains the return structure (opportunities[] with fields, partition_check in event mode, fill check results). Covers edge cases like skipped_low_similarity and placeholder filtering. Complete for a complex tool.

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

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

Both parameters (event, topic) have schema descriptions, and the description significantly expands on their meaning: explains event slug vs URL acceptance, single-event vs cross-event behavior, and internal checks (date-axis, threshold ordering, partition sum). Adds substantial value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from siblings like polymarket_edges and polymarket_fill_risk by detailing its specific arbitrage detection logic and referencing the fill risk tool for custom sizing.

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 on when to use each mode: no args for trending scan, 'event' for a specific market slug, 'topic' for cross-event scanning. It also explains when not to trade (fill check) and points to polymarket_fill_risk for custom sizing, providing clear alternatives.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) by detailing the three model families, the response structure, edge fields, tradeable-edge knobs, caching behavior (1h at KV level), and diagnostic information. It fully discloses the tool's behavior and limitations, such as the unreliability of Fed signals without paid data.

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

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

The description is lengthy (multiple paragraphs) but well-structured with clear headings (e.g., 'TRADEABLE-EDGE KNOBS', 'RESPONSE TOP-LEVEL'). It front-loads the main purpose and then provides detailed, organized information. While it could be slightly more concise, every sentence adds value given the tool's complexity.

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

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

Given 9 parameters, no output schema, and the tool's complexity, the description is remarkably complete. It details the entire response structure (by_segment, fed_*, _diagnostics), edge fields, and caching. An agent can fully understand what the tool returns and how to use parameters effectively.

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

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

The input schema covers all 9 parameters with descriptions. The description adds significant context beyond the schema, explaining how knobs like min_partition_leg_kelly work and why min_kelly doesn't filter partition arbs. It also provides examples and rationale, enhancing the agent's understanding of parameter interactions.

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 scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It uses a specific verb-resource combination ('Scan top Polymarket markets') and distinguishes itself from sibling tools like 'polymarket_arbitrage' by highlighting its focus on Pipeworx data disagreement and the specific model families.

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 it's built for 'what should I bet on today' and helps agents discover opportunities without paging hundreds of markets. It provides knobs like min_liquidity and max_spread_pp to filter out non-tradeable opportunities. While it doesn't explicitly say when not to use it, the context is clear and it offers guidance on when to apply the filters.

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

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

Annotations already indicate safe read-only, idempotent behavior. The description adds rich behavioral details: it reads historical snapshots, returns tracked/expired data, clarifies that decay is based on daily closes not intraday, and explains that snapshot dates have gaps. 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-organized, front-loading the purpose and using structured formatting for response fields. Though slightly verbose, every sentence adds value. Minor improvement could tighten some 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?

With no output schema, the description fully explains the return structure (tracked, expired, snapshot_dates) and their fields. It covers limitations and edge cases (e.g., median lifespan, snapshot gaps). Very complete for a complex tool.

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

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

Schema coverage is 100% so parameters are documented. The description adds value by providing defaults (14, '1wk'), ranges (clamp 2-30), and context about 'window family'. This supplements the schema without redundancy.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It uses specific verbs ('answers how long has this edge existed') and distinguishes from sibling tools like polymarket_edges, which likely provides current edge data.

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

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

The description implicitly guides when to use this tool (to understand edge history and decay) versus siblings (current edges). It also mentions limitations like TTL and snapshot gaps, giving context. However, it lacks explicit 'when not to use' or alternative tool names.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, establishing the tool's safe and non-destructive nature. The description adds rich behavioral details beyond annotations: it walks the ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, and explains risks like partial basket fills leading to unhedged positions. No contradictions with annotations.

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

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

The description is well-structured with clear sections: REQUIRES, SINGLE-MARKET, BASKET, and USE THIS. Every sentence adds value, such as specifying default sizes, return fields, and risk warnings. It is front-loaded with the core purpose and remains concise despite the complexity.

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

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

Given the tool's complexity (two modes, multiple return fields, no output schema), the description is remarkably complete. It covers all return fields (top_of_book, vwap_fill_price, etc.), explains the risk of thin books and partial fills, and provides concrete examples of use. With no output schema, the description takes on the full burden of explaining outputs, which it does thoroughly.

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

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

Schema description coverage is 100% (all 4 parameters have descriptions). The description adds significant meaning beyond the schema: it explains the two modes (market vs event), default behavior for side ('auto from partition sum'), and size_usd interpretation ('max spend on buys, target proceeds on sells' for single-market, 'settlement notional S (shares per leg)' for basket). This greatly aids correct parameter invocation.

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

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

The description clearly states the tool's purpose as a 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It differentiates between single-market and basket/partition modes, and explains what each mode returns, making it distinct from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books not capturable, partial basket fills convert arb into unhedged directional position), offering clear when-to-use and when-not-to-use context.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. The description adds significant behavioral context: compatibility warnings for non-equivalent bet shapes, temporal alignment checks, skipped comparison counters, and the caveat that 'pre-mapped ≠ tradeable'. No contradictions with annotations.

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

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

The description is quite long but well-structured with paragraphs and bullet points. It is information-dense, but every sentence earns its place given the complexity of the tool. Some conciseness could be improved by trimming redundant 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?

Given the tool has no output schema and 3 parameters, the description is thorough: covers modes, response structure (leg-by-leg prices, spreads, safety fields), temporal alignment, and skipped comparison types. 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% with descriptions for all three parameters. The description adds value by listing the exact topic shortcuts, explaining how explicit parameters override the topic, and providing context on their usage. The meaning is enriched 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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit tickers) and explains the output. This distinguishes it from siblings like polymarket_arbitrage which focus on single-venue arbitrage.

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

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

The description explains when to use each mode (topic for 10 shortcuts, explicit for custom pairs) and warns that most pre-mapped topics return compatibility warnings. It could be improved by explicitly stating when NOT to use (e.g., if no matching events).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral context: scoping to identifier, listing all keys when key omitted. No contradictions.

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

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

Two sentences with a dash, front-loaded. Every sentence adds value. Could be slightly more concise but good.

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

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

No output schema, so description should explain return format. It mentions retrieval and listing but not what the returned value looks like. Examples help. References siblings. Fairly complete for a simple 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?

Schema description coverage is 100% (key parameter described). Description adds meaning: omitting key lists all keys, and key relates to saved memory. Examples in schema help.

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

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

Description clearly states the verb 'Retrieve' and resource 'value previously saved via remember', and also 'list all saved keys'. It distinguishes from siblings by explicitly mentioning 'remember' and 'forget'. Examples of typical stored values add clarity.

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

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

Description clearly says when to use ('look up context stored earlier') and provides examples. It references sibling tools (remember, forget) but does not explicitly state when not to use or list alternatives. Context is clear enough.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, etc. Description adds that mark_read flag affects subsequent calls and that polling is fine, but does not detail rate limits or pagination. Moderate value beyond annotations.

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

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

Four sentences, no fluff. Front-loaded with core purpose, each sentence adds distinct information (returns, filters, state management, alternative access). Extremely concise 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?

No output schema, but description covers return fields. Mentions limit parameter implicitly via schema. Could discuss pagination or empty result behavior, but given simplicity, it's sufficiently complete for a read-only alert 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?

Schema covers all 5 parameters with descriptions (100% coverage). Description adds usage context: explains mark_read behavior, gives an example type (sec_8k), and mentions ISO timestamps for since. Adds meaningful value beyond schema.

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

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

The description clearly states it pulls fired events from the subscription feed, lists return fields (source, citation_uri, payload), and supports filtering by type and since. This distinguishes it from sibling tools like 'recent_changes' or 'list_subscriptions'.

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

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

Describes when to use (to get recent alerts), recommends polling, and provides an alternative endpoint for scripts/dashboards. Could explicitly state when not to use (e.g., for searching historical alerts) but offers solid context.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: parallel fan-out, fallback from GDELT to GNews on rate limit, soft-fail for USPTO due to API sunset, and the structure of returned data.

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 dense paragraph but is well-structured: starts with usage examples, explains sources, parameter format, and return structure. Every sentence adds value, though it could benefit from bullet points for 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 explains the return structure (changes[] grouped by source, total_changes count, citation URIs) and covers edge cases (fallback, soft-fail). For a tool with multiple data sources and complex behavior, this is highly complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra value by explaining 'since' accepts ISO dates or relative shorthand (examples given), and 'value' can be ticker or CIK. It recommends '30d' or '1m' for typical monitoring, enhancing usability.

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/weeks/months in ONE parallel call' and lists specific sources (SEC EDGAR, GDELT/GNews, USPTO). It also distinguishes from the sibling tool entity_profile, making the purpose 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 includes explicit when-to-use examples ('What's new with X', 'latest on Y') and a when-not-to-use directive ('Use entity_profile instead when you want the static profile'). It also explains fallback behavior for news sources.

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

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

The annotations indicate idempotentHint=true and destructiveHint=false. The description adds that data is scoped by identifier, that authenticated users get persistent memory, and anonymous users retain for 24 hours—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, well-structured paragraph that front-loads the main purpose. Every sentence adds essential information, without any redundancy or wasted words.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, usage, behavior, persistence, and sibling relationships comprehensively. It leaves no relevant 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?

The input schema already provides descriptions for key and value (100% coverage). The description adds value by giving example key patterns like 'subject_property' and clarifying what values can store, enhancing the schema's 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 that the tool saves key-value data for reuse across sessions or conversations. It gives specific examples (resolved ticker, user preference) and distinguishes it 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 tells when to use the tool: when you discover something worth carrying forward. It also explains how it pairs with recall and forget, and notes the persistence difference between authenticated and anonymous users.

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

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

The description goes well beyond the provided annotations (readOnly, openWorld, idempotent, non-destructive). It discloses graceful degradation of LEI/FIGI enrichment, explicit marking of unresolved identifiers, source labeling for identifiers, and internal cascading behavior. No contradiction with annotations.

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

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

The description is long but information-dense, including examples, explicit usage instruction, and format details. It is front-loaded with query examples that immediately convey scope. While it could be tighter, every sentence earns its place given the tool's complexity.

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

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

Despite no output schema, the description thoroughly explains return values: canonical IDs, source labels, unresolved identifiers, and fallback behavior. It also captures edge cases (unavailable GLEIF/OpenFIGI) and mentions cascading internals. The tool's behavior is well understood from the description.

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

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

The schema already provides property descriptions covering 100% of parameters, but the tool description adds substantial meaning by explaining accepted input formats (ticker, CIK, name), the distinction between company and drug behavior, and what identifiers are returned. This enriches the schema 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?

The description clearly identifies the tool's purpose: resolving user-spoken names to canonical/official identifiers required by other tools. It uses specific verbs ("resolve") and resources (entity types like company and drug), and distinguishes itself from siblings by explaining it produces the IDs other tools consume.

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 FIRST whenever you have a name but need an ID." It also provides context for when to use it versus alternatives by noting it replaces 2-3 manual lookups and supports specific entity types. It does not explicitly state when not to use it, but the guidance is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, establishing a safe, non-destructive operation. The description adds behavioral detail: it probes each entity with ai_visibility_check, ranks results, and returns a ranked list with score, confidence, and signal density. It also notes the first entity is treated as 'subject' for narrative. No contradictions with annotations.

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

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

The description consists of three targeted sentences: first states purpose, second explains workflow and ranking, third gives a concrete example and output summary. No filler or redundancy; 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 has 4 well-described parameters and no output schema, the description sufficiently covers what the tool does, how it works (calling ai_visibility_check), and what it returns (ranked list with score, confidence, signal density). An agent has enough information to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by clarifying constraints: entities must be 2-8 items, first is the subject, and context is shared across probes. This goes beyond the schema's basic descriptions, guiding proper use.

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

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

The description clearly states the tool compares AI visibility across multiple entities, using ai_visibility_check to probe each, ranking by score, and surfacing most/least recognized. It explicitly differentiates from sibling ai_visibility_check (single entity) and compare_entities (generic) by specifying AI-specific side-by-side comparison.

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

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

The description provides a clear use case (competitive AI-marketing audits) and an example question ('does Claude know about us as well as our competitors?'). It implicitly suggests using ai_visibility_check for single entity checks, but does not explicitly state when not to use this tool or list alternatives beyond the sibling 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 details behavioral traits beyond annotations, including fan-out behavior across two sources, partial failure handling ('sources_failed will list it if it times out'), and latency notes for bundlephobia's first measurement (5-30s). It also lists return fields, perfectly complementing the readOnlyHint and idempotentHint annotations.

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

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

The description is front-loaded with the core purpose and well-structured across usage, return format, limitations, and failure behavior. However, it is somewhat verbose, especially in enumerating return fields, which could be trimmed without losing clarity.

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

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

Given the tool's complexity (composite check with partial failures) and the absence of an output schema, the description provides comprehensive context: return fields, failure handling, latency notes, and ecosystem scope. It effectively covers all necessary information 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 description coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema's parameter descriptions (e.g., accepting scoped packages and version defaulting). The added context is minimal, so the score remains at baseline.

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

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

The description clearly states the tool's purpose as a composite check for npm packages, combining deps.dev and bundlephobia data. It specifically addresses the question 'should I add this npm package to my project' and distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on package analysis.

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

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

The description explicitly instructs when to use the tool: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also defines ecosystem limitations ('NPM ecosystem only in v1') and suggests an alternative for other ecosystems, providing clear guidance on appropriate usage.

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

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

Annotations already indicate read-only, idempotent, and open-world behavior. The description adds valuable details: BGE-base-en embeddings, 500-char overlapping windows, cosine similarity, 200K char cap with truncation flagging, and passage offsets. 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 with a concise first sentence, followed by detailed second paragraph. Every sentence adds value—purpose, use case, pairing, technical details—without redundancy.

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

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

Despite lacking an output schema, the description explains return values: top-N passages with offsets and similarity scores. It also covers truncation behavior and technical implementation, making it complete for understanding the tool's functionality.

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

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

Schema coverage is 100%, so baseline 3. The description does not add extra semantics beyond the schema's parameter descriptions, though it provides usage examples in the 'query' context.

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

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

The description clearly states the tool performs semantic search inside a fetched record, using specific examples like SEC 10-K and articles. It distinguishes itself from sibling tools like ask_pipeworx_grounded by explaining the workflow pairing.

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 advises using this tool when the record is too large for the prompt, saving context. It suggests pairing with ask_pipeworx_grounded, but does not explicitly state when not to use it, missing a clear 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 suggests each invocation creates a new subscription, contradicting the idempotentHint=true annotation which implies safe retry without duplication. This is a serious inconsistency that misleads the agent about idempotency.

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

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

The description is well-structured and front-loaded with the purpose, but it is verbose. Every sentence adds value, but some details (e.g., webhook verification) could be streamlined without losing clarity.

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

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

Given the tool's complexity (multiple types, delivery channels) and lack of output schema, the description covers key behavioral aspects (return value, OAuth requirement, rate limits, channel details). Minor gaps: no mention of error handling or partial success scenarios.

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?

Despite 100% schema coverage, the description adds extensive meaning beyond the schema: it details type-specific parameter formats (e.g., sec_8k items, fred_series series_id), delivery constraints (SMS cap, phone verification, webhook signature), and examples. This significantly aids correct parameter usage.

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

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

The description clearly states the tool creates a monitoring subscription, specifying the resource (live-data event stream) and action (create/subscribe). It distinguishes from siblings like unsubscribe and list_subscriptions by noting it returns a new subscription ID.

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

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

The description provides clear usage context, including prerequisites (Pipeworx OAuth account), supported types, and delivery options. However, it lacks explicit when-not-to-use guidance or direct comparison to sibling tools like list_subscriptions or unsubscribe.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. Description adds that it returns example questions with tool shapes, which is useful behavioral context beyond annotations. No contradictions, but could mention that the tool has no side effects.

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

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

The description is a single paragraph that front-loads the core purpose and includes all necessary details. While slightly verbose, it remains clear and efficient, earning its sentences.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description fully covers what the tool does, its return format, and when to use it. No gaps remain.

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

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

Schema coverage is 100% and description adds value by explaining the effect of omitting vs. providing the topic parameter (full spread vs. focused). The description clarifies semantics beyond the schema's brief description.

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

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

The description clearly states it is the onboarding entry point, returning category-bucketed example questions with exact tool + argument shapes. It distinguishes from siblings by being the first tool to use when the agent doesn't know what Pipeworx can do.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you'. Also explains optional topic parameter to focus the results, providing clear when-to-use guidance.

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

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

Annotations provide idempotentHint=true and destructiveHint=false. Description adds value by explaining ownership enforcement and that rows are deactivated (not deleted), preserving historical data through recent_alerts.

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. Every sentence provides essential information (action, ownership, deactivation behavior).

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

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

Simple tool with 1 param, no output schema. Description covers all necessary aspects: action, permission check, side effects, and data retention. Fully sufficient for invocation.

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

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

Schema coverage is 100% with description 'Subscription id (uuid) returned by subscribe.' Description adds no extra meaning beyond schema, baseline 3 is appropriate.

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

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

Description clearly states 'Cancel a subscription by id' with specific resource (subscription) and action (cancel). It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by explaining ownership enforcement and soft-deactivation behavior.

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 'you can only cancel your own subscriptions' providing context. No explicit 'when not to use', but the tool is straightforward and the idempotent hint covers retry safety.

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

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

Annotations provide readOnly/openWorld/idempotent hints, but the description adds high-value context: the exact verdict set, that could_not_verify means the check did not happen and must not be treated as evidence, that unsupported means no source exists, and the fast-path vs grounded pipeline behavior. This goes well beyond structured fields.

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

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

The description is longer than average but front-loaded with natural-language triggers and examples. Every sentence contributes—routing rules, return values, error semantics, efficiency benefit—with no filler. It could be trimmed slightly, but the density justifies the length.

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

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

With no output schema, the description compensates by enumerating all possible verdicts, explaining error semantics, mentioning the citation format, and clarifying source routing. This fully equips an agent to invoke the tool and interpret results, even in 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?

Schema covers 100% of parameters, so baseline is 3. The description adds meaningful guidance: concrete example strings for the claim parameter, and for tolerance_pct it explains overriding the implied tolerance, suggests 1–2 for hallucination detection, and notes the default cap of 5. This enriches the schema's dry parameter 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 states a specific verb and resource: 'natural-language claim verification against authoritative sources.' It distinguishes from sibling tools by explicitly explaining it replaces 4–6 sequential calls and by splitting financial vs non-financial verification paths, making its niche clear.

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

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

It gives an explicit trigger: 'Use whenever the agent needs to check whether something a user said is factually correct.' It then provides a branching rule for company-financial claims vs all others, and clarifies the critical distinction between could_not_verify and unsupported, which prevents misuse.

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