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 by explaining that the tool routes internally, auto-fills arguments, and returns structured answers with stable citation URIs. It could mention failure or unanswerable cases, but it exceeds what annotations provide.

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

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

The description is long but front-loaded with the most critical routing guidance, followed by concrete examples and escalation rules. Every sentence contributes useful selection or invocation information, though it is denser than strictly necessary.

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

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

Despite the lack of an output schema, the description explains the key return characteristic: a structured answer with pipeworx:// citation URIs. Combined with the single required question parameter, comprehensive usage triggers, and explicit alternatives, the description is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the parameter meaning and aliases are already fully documented in the input schema. The description reinforces this with examples and natural-language triggers, but it doesn't add new meaning beyond the schema.

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

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

The description clearly states the tool's function: it routes questions to one of 5,767 tools across 1,506 verified sources and returns structured answers with pipeworx:// citation URIs. It goes beyond the name/title and explicitly distinguishes itself from web search and sibling tools like deep_research.

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

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

The description provides explicit when-to-use guidance: prefer over web search for a broad list of domains and trigger phrases such as 'what is', 'look up', 'find', and 'current'. It also names deep_research as the alternative for broad/multi-part questions, giving clear routing instructions.

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 annotations by revealing the live candidate routing mechanism, stating that no candidate is currently active, explaining that it currently matches ask_pipeworx exactly, and clarifying that it is a full working router with no fallback. This is rich behavioral context that directly affects how an agent should treat the tool.

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 identity, current state, and usage guidance in a compact four-sentence structure. The specific retirement date is arguably extra detail, but it supports the claim that no candidate is active without making the description unwieldy.

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

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

Given that this is a beta variant of a known sibling, the description covers what it is, how it behaves, when to use it, and that the response shape matches ask_pipeworx. It does not describe the response format itself, but the explicit pointer to ask_pipeworx is enough when the sibling is available for reference.

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

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

The input schema covers 100% of the parameters, including aliases and a full description of the question parameter. The description only says 'same arguments' and does not add parameter-specific semantics. 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 identifies the tool as the beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It explicitly distinguishes it from the stable sibling by framing it as the experimental edge, so an agent can understand exactly what this tool is for.

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 an explicit usage condition: use it exactly like ask_pipeworx when you want the newest routing. It also explains that results are compared against the stable router to decide merges. It does not provide an explicit exclusion such as 'use ask_pipeworx for production', though the 'experimental edge' language implies it.

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

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

Adds substantial behavioral context beyond readOnlyHint and idempotentHint: it discloses refusal behavior, exact refusal_reason values, no-invention guarantees, and return payload shape. These details align with the annotations and tell the agent what can and cannot happen.

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 clause earns its place: purpose, mechanics, return/refusal contract, use cases, and trade-off are packed into a compact description. The opening phrase immediately signals the tool's value proposition without needing to read the schema.

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

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

Covers all decision-relevant information: mode definition, routing mechanism, response shape, refusal enum, high-stakes use cases, and comparison to the sibling tool. With no output schema, the explicit return payload and refusal reasons are necessary and sufficiently 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?

The schema already documents the single question parameter with 100% coverage, including its natural-language nature and all aliases. The description adds no field-level semantics beyond what the schema provides, 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?

States a specific mode — grounded, hallucination-resistant Q&A — and explicitly mentions identical routing to ask_pipeworx. It clearly distinguishes itself by promising evidence-grounded extraction and explicit refusal when the data doesn't answer.

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 use guidance: prefer grounded mode when answers will be quoted, cited, or acted on, and prefer ask_pipeworx for casual lookups. The extra LLM call cost is an explicit trade-off to help the agent decide.

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

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

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?

Annotations already signal safety (readOnly, openWorld, idempotent, non-destructive), and the description adds rich behavior beyond that: it returns a findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, explicit gaps[], and states it 'never invented' — plus latency expectations. This fully discloses what the agent should expect.

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 deliberately packed with non-redundant operational facts: auth, alternative tool, data scope, output shape, latency, and examples. It is front-loaded with the most decision-critical constraint (ACCOUNT REQUIRED) and 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?

There is no output schema, so the description correctly carries the burden of explaining return values — it does in detail (findings packet, gaps[], contradictions, citations). It also covers auth, pricing, latency, scope boundaries, and use cases, making it complete enough for correct invocation.

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

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

Schema description coverage is 100%: both `question` and `depth` are already well documented in the input schema, including the paid nature of `thorough`. The description adds little parameter-level meaning beyond that baseline, so the schema carries the burden and a 3 is appropriate.

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

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

Description states a specific verb+resource: 'grounded multi-source research across Pipewor x's 1506 STRUCTURED data sources' and explains it decomposes questions into facets and routes them across 5,767 tools in parallel. It also distinguishes itself from open-web search and from ask_pipeworx, so an agent can select it correctly.

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 says when to use this tool ('best for broad/multi-part questions over structured data') and when not to ('For a single lookup use ask_pipeworx instead'), plus the auth condition ('If you are not signed in, use ask_pipeworx instead') — providing clear routing to alternatives.

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

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

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?

Annotations already mark the tool as read-only and idempotent, and the description adds substantial behavioral context: parallel fan-out across sources, sources_used/sources_failed semantics, empty sections meaning real absence of data rather than a bug, resolved_from/resolved_to behavior, and the resolved:false path for private companies. This goes well beyond what annotations alone convey.

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

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

The description is rich but overlong and somewhat unstructured, with repeated schema information such as valid value forms and interchangeable type values. It is front-loaded with user intents and core guidance, but the dense single-block format and redundant examples keep it from being 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?

With no output schema, the description carries the burden of explaining return content, and it does so thoroughly: CIK, company name, resolution fields, recent filings with URIs, fundamentals, source success/failure flags, and private-company behavior. It also covers edge cases like empty sections and failed name resolution, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful usage detail beyond the schema: both type values are interchangeable, names resolve via SEC EDGAR, zero-padded CIKs are expected, and the resolved_from/resolved_to nuance is tied to name inputs. This extra context justifies a 4.

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

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

The description clearly states the tool produces a full cross-source profile of a US public company in one parallel call, and lists concrete user intents like 'Tell me about X' and 'company profile for Microsoft'. It also distinguishes itself from chaining single-pack SEC/XBRL/news lookups, making its scope and resource 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?

The description gives explicit trigger examples and says to prefer this tool over chaining single-source lookups when a holistic view is requested. It does not explicitly compare against sibling tools like compare_entities or deep_research, but the guidance for when to use it is strong and actionable.

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

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

Annotations already 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?

Beyond the readOnly/idempotent open-world annotations, the description discloses many non-obvious behaviors: compatibility_codes semantics, pairing_unverified being set whenever pairs are returned, unclassified legs never being paired, null temporal_alignment meaning 'could not be computed' rather than 'aligned,' and fees being gross rather than net tradeable edge. This is rich, useful behavioral context with no contradiction to annotations.

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

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

The description is long but front-loaded with the core purpose and modes before going into safety details and response fields. Most sentences carry unique operational information, and there is no fluff. It could be tightened, given its density, but the length is largely justified by the complexity of the output and compatibility semantics.

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?

There is no output schema, so the description carries the full burden of explaining return values. It enumerates the response components: leg-by-leg prices, top_spreads_pp, compatibility_warning/codes, skipped counters, temporal_alignment, fees_note, and per-entry flags. It also explains null semantics and the meaning of each compatibility code. This is more than enough for an agent to understand what the tool returns and how to interpret it.

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

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

All three parameters already have clear descriptions in the schema (100% coverage), so the baseline is 3. The description adds context about how the parameters combine—topic fetches a preset, explicit ticker/slug overrides the mapped side—and lists the valid topic values, but this is largely redundant or supplemental rather than essential. No parameter is left unexplained, but the description does not add substantial semantic depth beyond the schema.

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

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

The description opens with a precise statement of function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It names the two venues, the comparison being made, and the underlying concept of price deltas on equivalent outcomes. It is clearly distinguishable from sibling tools like polymarket_arbitrage and polymarket_edges because it emphasizes the cross-venue, same-question 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 gives explicit mode selection guidance: topic mode for pre-mapped shortcuts, explicit mode for custom ticker/slug pairings, and clarifies that both modes run the identical token-overlap matcher. It also warns that most pre-mapped topics currently return compatibility warnings and that 'pre-mapped ≠ tradeable.' However, it does not explicitly contrast this tool against sibling tools for when one should be preferred over the other.

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?

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, but the description goes far beyond that, detailing fallback behavior when GLEIF/OpenFIGI is unavailable, how unresolved identifiers are explicitly listed, and how multiple lookups are cascaded internally. This adds significant context an agent needs to anticipate outcomes and 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 extremely long and dense, covering every possible detail, source, and edge case. While front-loaded with the purpose and 'Use FIRST' directive, the sheer volume may overwhelm an agent and obscure the essential points. It could be significantly condensed without losing critical guidance.

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

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

For a tool with only 2 parameters and no output schema, the description exhaustively covers inputs, outputs, edge cases, fallbacks, and source details. Even though the output schema is absent, the description explains what to expect (e.g., 'unresolved' field, source labels). An agent has all necessary information to invoke this tool correctly in any scenario.

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

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

The schema descriptions for 'type' and 'value' are already robust, with examples and specific instructions (e.g., passing entity name only for bonds). The tool description reinforces these semantics with additional nuance, such as the exact pronunciation of issuer names and the risk of trailing security-class words. This goes beyond the schema and clarifies usage precisely.

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

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

The description opens with multiple query examples and explicitly states the core function: resolve a user-spoken NAME to canonical/official identifiers. It distinguishes itself from sibling tools like compare_entities and entity_profile by focusing on name-to-ID resolution, and further clarifies scope across company and drug types, making its purpose unmistakable.

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

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

It explicitly instructs 'Use FIRST whenever you have a name but need an ID,' which is a clear when-to-use directive. It also explains the cascading lookup behavior that replaces manual lookups. However, it does not explicitly state when not to use this tool (e.g., when an ID is already known), though the context strongly implies it. The absence of named alternatives is a slight gap.

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.