Woocommerce

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

Annotations already indicate safe, non-destructive, idempotent behavior. Description adds beyond: specifies default model (Workers AI Llama-3.3-70b) with cost note ('free'), explains that providing `_apiKey` triggers separate Anthropic calls (BYO key, direct payment), and outlines return structure (per-model {score, confidence, signals, raw_response} + combined view).

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 well-structured sentences: first covers purpose, default model, and key behavioral note; second covers return structure and use cases. No redundant words, front-loaded with the most critical information.

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

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

Description adequately explains all four parameters (entity, models, _apiKey, context) and return structure. No output schema exists, but description compensates with a clear outline of per-model response fields. Missing error handling or edge cases, but for a probe tool with these annotations, it is sufficiently complete.

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

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

Schema description coverage is 100% with each parameter already explained. The description adds minimal extra meaning beyond summarizing: e.g., 'Default model is Workers AI Llama-3.3-70b (free)' is already in schema's models description, and 'Pass `_apiKey` to also probe Anthropic' is also in schema. It provides context but not significant new details.

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

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

Description starts with a clear verb ('Probe'), specifies the resource ('LLMs for visibility'), and gives a concrete output ('score 0-100 per model'). It distinguishes itself from siblings like 'ask_pipeworx' (general QA) and 'scan_competitor_ai_presence' (competitor-focused audit) by focusing on any entity and providing a quantified visibility score.

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

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

Explicitly states use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains when to provide `_apiKey` (for Anthropic) and implies when not needed (just workers-ai). Does not explicitly list when NOT to use, but context signals differentiate from siblings.

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

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

Annotations already cover read-only, open-world, idempotent, non-destructive behavior. The description adds useful behavioral context beyond that: it is an automatic router that fills argument slots and returns structured answers with stable pipeworx:// citation URIs. It does not discuss failure modes, rate limits, or latency, but that is not a major gap for a read-only query router.

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

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

The description is front-loaded with the most important instruction ('PREFER OVER WEB SEARCH') and packs a lot of routing guidance, examples, and alternatives into a readable block. It is long but each part earns its place, though the tail becomes a bit list-heavy and the run-on alternatives sentence could be tightened.

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

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

For an open-ended natural-language query tool with no output schema, the description covers the required input (a factual question), return behavior (structured answer with citation URIs), source scope, trigger phrases, example queries, and explicit fallback/alternative tools. An agent has enough context 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%, and every parameter is documented as an alias for the natural-language question. The description reinforces that input is a natural-language factual question, and the examples illustrate what a good query looks like, but it does not need to add much 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 names a specific function: it routes factual questions to one of 5,767 tools across 1,506 verified sources, fills arguments, and returns a cited structured answer. This is a concrete verb+resource statement and is distinct from siblings like deep_research and ask_pipeworx_grounded.

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

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

It gives explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE for most questions'), trigger phrases ('what is', 'look up', 'find', 'get the latest'), example questions, and names alternatives with the conditions that select them (ask_pipeworx_grounded for evidence-heavy multi-lingual investigation, deep_research for broad multi-part questions).

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

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

With annotations already covering readOnly, openWorld, idempotent, and non-destructive behavior, the description adds meaningful context: no candidate is currently active, it currently matches ask_pipeworx exactly, and results feed comparison against the stable router. It also honestly discloses that routing improvements may be enabled live under test.

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 each carry distinct information: identity, current state, usage, and reassurance. There is minor redundancy between 'identical universal router' and 'matches ask_pipeworx exactly,' but the description is not padded.

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

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

The description covers scope, current experimental state, usage, and a pointer to the response shape being identical to ask_pipeworx. Without an output schema, an agent might still want more detail on the exact response format, but this is deferred to the sibling definition.

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 the `question` parameter and its aliases. The description's 'same arguments' cross-reference to ask_pipeworx is useful, but it adds no new parameter-level detail 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 opens by identifying this as the beta version of ask_pipeworx and as an identical universal router with the same 5,767 tools, arguments, and response shape. It later adds 'this IS a full working router,' which clarifies its role and distinguishes it from stable siblings.

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

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

The description says 'Use it exactly like ask_pipeworx when you want the newest routing,' which gives an explicit condition for selection. It does not explicitly state when not to use it or name ask_pipeworx as the stable alternative for non-experimental use, leaving the contrast mostly implicit.

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

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

Despite strong annotations, the description adds real behavioral context: exact success return shape, explicit refusal reasons, the constraint that answers come only from tool results, and the extra LLM call cost. It does not contradict any 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?

Dense and front-loaded: core behavior, return contract, usage trigger, and cost/alternative each earn their place. There is no filler or repetition of schema content.

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

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

Given no output schema, the description supplies the full success/refusal contract, failure reasons, usage context, and cost comparison. Annotations cover safety and schema covers parameters, so no critical gap remains.

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

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

Schema coverage is 100% and the schema already documents the question parameter plus aliases, so the baseline is 3. The description adds no parameter-specific detail, but none is necessary here.

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 purpose: hallucination-resistant answer extraction for high-stakes reads, using only the fetched tool result. It clearly differentiates from sibling ask_pipeworx by the grounded extraction behavior and explicit refusal contract.

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?

Gives explicit positive guidance ('Use whenever an answer will be quoted, cited, or acted on') and explicit negative guidance ('prefer ask_pipeworx for casual lookups'), including the cost trade-off of one extra LLM call.

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

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

The description provides extensive behavioral details beyond annotations, such as low-confidence resolution blocking, closed market handling, wide-spread warnings, cancellation rule parsing, and fallback mechanisms for news sources. Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, and the description is consistent.

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

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

The description is very long (nearly 1500 words) and could be more concise. While the information is valuable, it lacks front-loading of key points and includes extensive examples and fan-out details that might be better summarized. The structure is reasonable but not optimally efficient.

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

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

Given the tool's complexity (multiple classifications, fan-outs, response shapes, edge cases), the description is remarkably complete. It covers all behavioral scenarios, response structure hints, and error conditions. No output schema exists, so the description carries full burden and does so thoroughly.

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

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

Schema coverage is 100%, so baseline is 3. However, the description adds significant meaning: explaining the 'market' parameter accepts slug, URL, or question text; detailing 'depth' as quick vs thorough with defaults; and clarifying 'include_raw' with size estimates and usage context. This goes well 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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It also provides use cases ('should I bet on X', etc.) and explains the process. However, it does not explicitly differentiate itself from sibling tools like polymarket_edges or polymarket_arbitrage, which could lead to confusion.

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

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

The description gives clear usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also advises inspecting market_match_confidence before trusting analysis and explains when fields like parent_event are relevant. No explicit when-not-to-use or alternative tools are mentioned.

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

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

Adds significant context beyond annotations: explains data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handles off-calendar fiscal years, results sorted by primary metric, returns citation URIs. No contradiction with annotations.

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

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

Highly concise with zero wasted words. Front-loaded with query examples, then behavior, then data source details. 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?

Covers both entity types, explains return format (paired data + citations). No output schema, but description adequately explains what to expect. Could mention whether results are cached or real-time, but overall complete for effective use.

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

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

Schema already covers parameters with 100% description coverage. Description enriches by specifying behavior per type (company vs drug) and constraints on values (max 5 items, min 2). Adds meaning beyond schema definitions.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs, with specific verb examples like 'compare', 'vs', 'rank'. It distinguishes from siblings like entity_profile by focusing on comparison rather than single-entity lookup.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups' and provides clear context for when to use (comparing companies or drugs). Lacks explicit 'do not use when' but the guidance is strong enough for effective selection.

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

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

Annotations already mark this as read-only, open-world, idempotent, and non-destructive, and the description adds substantial behavior beyond that: it never invents gaps, returns verbatim evidence with confidence/source/fetched_at, cites via stable pipeworx:// URIs, detects contradictions at standard/thorough depths, semantically excerpts long records, and gives expected latency. No contradiction with annotations exists.

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

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

The description is long but front-loaded with the critical account constraint and use-case distinction, and most sentences add valuable operational context for a complex tool. It loses a point for redundancy, notably repeating the 'use ask_pipeworx instead' instruction, which could be tightened without losing information.

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

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

For a two-parameter tool with no output schema, the description is remarkably complete: it covers prerequisites, alternatives, scope, internal behavior, output format, gaps, contradictions, citation semantics, long-record handling, and runtime expectations. Nothing an agent needs to decide whether and how to invoke this tool is missing.

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

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

The schema already documents both parameters fully (question is natural language, depth explains facet counts and hops), so the baseline is 3. The description adds meaningful non-schema context: the 'thorough' depth requires a paid plan, the expected latency by depth, and which depths include contradiction detection, which helps an agent choose depth correctly.

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

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

The description uses a specific verb+resource framing: grounded multi-source research across Pipeworx's structured data sources, decomposing questions into facets and routing to tools in parallel. It explicitly distinguishes itself from open-web search and from ask_pipeworx, so an agent can tell it apart from key siblings without inspecting schemas.

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

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

The description gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, and not for single lookups, where ask_pipeworx is preferred. It also states the account prerequisite and that unsigned-in users should use ask_pipeworx instead, making the routing decision unambiguous.

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, idempotentHint=true. The description adds valuable behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond the annotations but does not contradict them.

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

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

The description is relatively concise (3-4 sentences) and front-loads the purpose. The list of domains adds length but is relevant for clarifying scope. Some minor redundancy with 'search, look up, or discover' could be trimmed, but overall it is well-structured.

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

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

Given the tool's simplicity (one required parameter, no output schema), the description fully covers the purpose, usage context, and return format. It explains that results include schemas and examples, which compensates for the lack of an output schema. No additional information is necessary.

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 meaning beyond the schema; it repeats that the tool accepts a natural language query and lists domains, but the schema already defines the query parameter with aliases and examples. No extra semantic value is provided.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It distinguishes from siblings by explicitly recommending to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' The verb 'discover' is specific and well-supported.

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 context for when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist' and advises calling it first to see options. However, it does not explicitly state when not to use it or name alternative tools, though the guidance 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 mark the tool as readOnly, idempotent, and non-destructive, and the description goes well beyond them. It discloses multi-source fan-out, per-source soft-fail behavior (PatentsView sunset), empty-section semantics ('a real "no data", not a bug'), private-company resolution behavior, and the meaning of sources_used/sources_failed.

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

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

The description is long but information-dense and well-structured with semicolon-separated sections. Some redundancy exists (repeated 'company/ticker interchangeable' idea and example-heavy opener), but almost every sentence adds operational detail an agent needs for this complex multi-source tool.

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

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

With no output schema present, the description carries the full burden of explaining return values, and it does so thoroughly: it enumerates every returned section, explains non-obvious results like empty fda_products, notes source failure vs. no-data, and describes resolution failure behavior. Nothing essential is missing 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 the parameters are already documented; the description still adds value by clarifying that 'company' and 'ticker' are interchangeable, that value can be a ticker, zero-padded CIK, or company name, and how name resolution works via SEC EDGAR. The private-company resolved:false behavior is also useful context beyond the raw 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 many concrete user phrasings, then defines the tool precisely: a 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes this from single-pack SEC/XBRL/news lookups and from sibling tools by emphasizing the holistic, aggregated nature.

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

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

It explicitly states when to use this tool ('when the user asks for a holistic view') and gives an explicit preference rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' It also covers input-format selection and the private-company case, so an agent knows both when and how to invoke 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?

The description aligns with annotations (destructiveHint=true, idempotentHint=true) but adds only minor context ('clear sensitive data'). Annotations already cover the key behavioral traits, so the description adds marginal value beyond them.

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

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

The description is extremely concise, consisting of two sentences. The first sentence states the purpose, and the second provides usage guidance and relationships. No extraneous content.

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

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

For a simple deletion tool with one parameter and no output schema, the description covers purpose, usage contexts, and pairing with siblings. It is sufficient for an agent to understand when and how to invoke the tool, though it could briefly mention idempotency or return behavior.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter ('Memory key to delete'). The description does not provide additional parameter semantics beyond what the schema already states, so baseline score applies.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying the action and resource. It distinguishes from sibling tools by mentioning pairing with 'remember' and 'recall', making the role in the memory triad 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?

Provides explicit scenarios for use: stale context, task completion, clearing sensitive data. Also advises pairing with related tools. However, it does not explicitly state when not to use this tool or list alternatives for non-deletion operations.

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

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

Annotations already declare readOnly=true, idempotent=true, non-destructive. Description adds behavioral context: fetches page, extracts title/description/key links, emits markdown. No contradictions, but could mention potential rate limits or size constraints.

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, front-loaded with the main purpose, and every sentence adds value. No unnecessary words or redundancies.

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

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

Given the tool's simplicity (2 params, no output schema, good annotations), the description fully covers what the tool does, its output format, and use cases. No gaps.

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

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

Schema coverage is 100% with clear descriptions for both 'url' and 'max_links'. The description does not add significant meaning beyond the schema, so 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 generates an llms.txt file for any URL, specifying the resource (llms.txt file) and action (generate/emit). It distinguishes from siblings as no other sibling tool performs this specific function.

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 (client indexing, personal projects, competitor auditing) but does not explicitly state when to avoid using the tool. However, the context is clear enough for an AI agent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds that it returns active subscriptions (default) and lists specific fields, complementing annotations without contradicting them.

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

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

Two concise sentences, no fluff. Purpose and usage are front-loaded, and every sentence adds value.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers purpose, return fields, usage context, and parameter implication.

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% for the single parameter 'include_inactive'. Description implies default behavior (active only), adding minimal value beyond the schema's 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?

Description uses specific verb 'List' and resource 'subscriptions', clearly distinguishing from sibling tools like subscribe/unsubscribe. It also enumerates returned fields (id, type, params, etc.).

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?

States 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear when-to-use guidance. Not explicitly mentioning alternatives, but context suggests siblings handle mutations.

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

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

Beyond the annotations (all false), the description discloses that filing returns a claim_token, is rate-limited to 5 per identifier per day, is free, and doesn't count against quota. It explains how to check status later and that the team reads digests daily, providing rich behavioral context.

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 typical but every sentence serves a purpose: use cases, exclusions, claim_token flow, rate limits, and cost. It is front-loaded with the core action and remains dense without padding, though it could be slightly more structured with paragraphs.

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

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

With no output schema, the description thoroughly explains return behavior (claim_token), scope, limitations, and operational details. It covers intent, disambiguation, rate limits, and follow-up usage, making it complete for a feedback tool with four 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?

The schema already covers all parameters with 100% description coverage, so baseline is 3. The description adds valuable usage guidance for `message` (don't paste end-user prompt) and `claim_token` (how to use it to read replies), improving parameter understanding beyond the schema.

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

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

The description clearly states the tool's action: reporting broken/missing features or praise to the Pipeworx team. It uses specific verbs like 'Tell' and 'file' and distinguishes itself from sibling ask_pipeworx tools by focusing on feedback rather than asking questions.

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. It also states when not to use: for tools from a different MCP server, and directs users to file with that server instead. This gives clear decision criteria.

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, non-destructive. The description adds valuable context: self-aggregating, derived from CF analytics-engine, no PII, caching behavior (5min-1h). No contradictions.

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

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

The description is concise, front-loaded with the main output, followed by use cases and technical details. Every sentence adds value without redundancy.

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

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

Given one optional parameter, no output schema, and rich annotations, the description fully covers behavior, use cases, and caching. 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?

Only one parameter (window) with 100% schema coverage. The description adds meaning by explaining that shorter windows surface hot items and longer windows show steady-state demand, enhancing the enum values.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a specific window. It uses specific verbs and distinguishes from sibling tools by focusing on trending call 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 provides explicit use cases (discovering hot data, confirming canonical tools, aligning with most agents' needs). It does not explicitly mention when not to use it or alternative tools, but the listed scenarios offer clear guidance.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds extensive behavioral context: response structure, fill check logic, semantic anchor requirements, and partition filter details. No contradictions with annotations.

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

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

The description is quite long but every sentence adds essential detail for a complex tool. It is front-loaded with purpose and modes, and structured logically. Slight verbosity is justified by the tool's complexity, but could be trimmed slightly without losing clarity.

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

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

Despite no output schema, the description thoroughly explains the response structure, fill check logic, and edge cases (low similarity, placeholder filters). It also references a sibling tool for further needs, making it self-contained and complete for an agent to understand 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 covers 100% of parameters. The description adds significant value beyond schema by explaining the behavior of each parameter, providing example inputs, and detailing what happens in each mode (e.g., cross-event scanning, fill check 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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific behaviors, making its purpose unambiguous and differentiating it from sibling Polymarket 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 advises when to use each mode: no args for trending scan, event for specific markets, topic for cross-event scanning. Provides examples of valid inputs and warns against trading when fill check shows non-realizable edge, with a pointer to a sibling tool for custom sizing.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds significant behavioral context: caching ('Cached 1h at the KV level keyed on all knobs'), response structure (by_segment, diagnostics), and details on how edges are computed (e.g., slippage subtraction, Kelly caps). No contradictions with annotations.

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

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

The description is very long and dense, with detailed technical explanations of model families and edge computation. While it is structured with sections and parentheses, it could be more concise to improve readability for an agent. The first sentence is clear, but the overall length may hinder quick comprehension.

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

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

The description is comprehensive for a complex tool with 9 parameters and no output schema. It explains the three response segments, diagnostics, filtering knobs, edge cases (Fed bets), and caching strategy. It covers what the tool does, what it returns, and why certain opportunities may be excluded, making it fully functional 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?

Input schema has 100% description coverage, so the baseline is 3. The description adds some context for parameters like min_partition_leg_kelly and explains how tradeable-edge knobs work, but much of the parameter meaning is already clear from the schema. The description does not significantly enhance parameter understanding beyond what the schema provides.

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It uses a specific verb ('scan'), names the resource, and distinguishes from sibling tools like polymarket_arbitrage by focusing on edge detection and model-driven signals.

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

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

The description explicitly states it is built for 'what should I bet on today' and highlights that agents can discover opportunities without paging through many markets. It also notes that Fed bets are excluded from ranking due to unreliable signals, providing a clear when-not-to-use scenario. However, it does not explicitly list alternatives among siblings.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are consistent with description. The description adds extensive behavioral details: time-series data, first_seen, trend, decay_pp_per_day, expired opportunities, and snapshot_dates. 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 lengthy but densely packed with essential information. It is front-loaded with the core purpose, then explains the response format and limitations. Every sentence adds value, though a slight reduction in length would improve conciseness.

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

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

With no output schema, the description thoroughly explains the return values: tracked[], expired[], snapshot_dates[] with fields and meanings. It also covers data freshness, limitations, and computation basis. Complete for a tool of this 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% with descriptions for both parameters. The description adds default values and clarifies the 'snapshot family' concept, but does not significantly extend beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question about edge age and decay, distinguishing it from sibling tools like polymarket_edges which likely provide current 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 clear context for when to use the tool, e.g., 'a fresh wide edge and a 3-week-old wide edge are different trades' and includes limitations like history depth bounded by 60-day TTL and decay from daily closes. It does not explicitly state when not to use alternatives, but the context is sufficient.

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 beyond annotations by detailing the tool's behavior: walking the ladder, returning fill details, auto-detecting side in basket mode, and identifying thin legs and forced directional risk. This adds rich behavioral context not captured by 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 well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Every sentence adds value, using concise formatting like ALL CAPS for key requirements and avoiding redundancy. It is thorough yet not overly verbose.

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

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

Given the complexity of two modes and lack of output schema, the description fully covers both modes, all input parameters, and all return fields (e.g., top_of_book, vwap_fill_price, capture_ratio, thin_legs, forced_directional_risk). No gaps remain for an agent to understand what the tool does and what it returns.

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

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

Schema description coverage is 100%, and the description adds significant extra meaning: explains defaults (size_usd=1000, side auto-detection), clarifies interpretation of size_usd for single vs basket, and describes automatic side selection in basket mode. This goes well beyond what the schema provides.

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

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

The description clearly states the tool performs a realizable vs theoretical edge check against live order-book depth. It distinguishes single-market and basket modes, listing specific outputs for each, making its purpose highly specific and distinct from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

Explicitly recommends use before acting on polymarket_arbitrage signals or trades above $500, and warns of the dominant loss mode from partial fills. This provides clear when-to-use and when-not-to-use guidance with direct reference 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?

The description goes far beyond the readOnly/idempotent/OpenWorld annotations. It discloses that fees are gross ('does not model Kalshi's fee schedule'), that pairings are keyword-based and unverified ('pairing_unverified'), that unknown metric types are never paired, that `temporal_alignment` null is not equality, and that compatibility warnings can appear even with matched pairs. It also explains all safety codes and skipped counters.

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

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

The description is very long but intelligently structured with labeled sections (RESPONSE, SAFETY FIELDS, Codes, etc.) and front-loads the core purpose. Nearly every sentence carries unique information about behavior or edge cases. Some repetition of `temporal_alignment_unknown` and the dense code-list could be tightened, but for a tool this complex the length is mostly justified.

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

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

No output schema exists, so the description carries full responsibility for explaining return values, and it does so thoroughly: leg-by-leg prices, top_spreads_pp, compatibility_codes[], temporal_alignment, fees_note, skipped counters, and low_confidence_pairs. It also documents important null semantics and which legs are never paired, 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% (all three parameters documented, including override behavior for tickers/slugs), so baseline is 3. The description adds value by explaining the two-mode architecture, the pre-mapped topic list, and that both modes run the same token-overlap matcher. It clarifies that `kalshi_event_ticker` and `polymarket_event_slug` can override the topic-derived side, deepening the schema's notes.

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 opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage by naming the exact cross-venue computation and then details two operational modes. The purpose is unmistakable and an agent can immediately tell which of the many polymarket/arbitrage siblings this is.

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 strong context: TWO MODES, with `topic` for 10 pre-mapped shortcuts and explicit ticker/slug for custom pairings, and warns that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It tells the agent when to use each mode and sets expectations, though it never explicitly names alternative sibling tools to consider instead.

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?

Consistent with annotations (readOnlyHint, idempotentHint, destructiveHint). Adds context on scoping and listing behavior, but does not describe error handling or return format.

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

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

Three sentences, front-loaded, no waste. Every sentence serves a purpose.

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

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

Explains use case, scoping, and pairing with siblings. Lacks return format description but is adequate for a simple tool with no 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?

Schema already describes the parameter well ('omit to list all keys'). Description adds context about being saved via remember and examples, but adds limited extra value beyond schema.

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

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

The description clearly states the tool retrieves a value by key or lists all keys, and distinguishes it from siblings (remember, forget) by focusing on retrieval.

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 when to use (to look up previously stored context), provides examples, implies when not to use (not for saving/deleting), and mentions scoping by identifier.

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 nondestructive nature. The description adds value by explaining the mark_read behavior (flags events as read for subsequent calls) and noting that polling is acceptable, going 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 paragraph that is informative without being verbose. It front-loads the main purpose and efficiently covers return fields, filtering, and special behavior, though it could be slightly restructured 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?

Given no output schema, the description adequately explains return values (source, citation_uri, payload). It mentions parameter limits (1-200, default 50) and poll safety. Lacks explicit pagination details but is otherwise complete for a read tool with strong annotations.

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

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

Schema coverage is 100%, so the schema already documents parameters. The description adds meaningful context by providing concrete examples for type ('sec_8k') and since (ISO timestamp), and explaining the effect of mark_read, which enhances understanding beyond the schema.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifying the exact resource and verb. It lists the key fields returned (source, citation_uri, payload), which distinguishes it from abstract or vague tool descriptions.

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

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

The description does not explicitly compare this tool to siblings or state when to use it over alternatives. However, it implies usage for retrieving the most recent alerts and mentions an alternative endpoint for scripts, offering indirect 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 declare read-only, idempotent, etc. Description adds fallback behavior (GDELT→GNews), API sunset note, and structured return format, going 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?

Well-structured with front-loaded examples, but slightly dense; every sentence adds value, though could be trimmed slightly.

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

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

Despite no output schema, description explains output structure (changes grouped by source, total_changes, citation URIs). Covers fallback and limitations.

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

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

Schema already covers 100% with descriptions; description elaborates on 'since' with relative formats and 'value' with ticker/CIK examples, adding value.

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

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

Description clearly states the tool provides a 'change feed for a company' from multiple sources (SEC, GDELT/GNews, USPTO) and contrasts with sibling 'entity_profile'.

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

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

Explicitly gives example queries and when to use 'entity_profile' instead. Provides guidance on 'since' parameter usage with relative shorthand.

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 (idempotent, non-destructive), description adds scoping by identifier, persistent vs temporary memory, and lifetime details. 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?

Three well-structured sentences, front-loaded with purpose, no extraneous text. Every sentence adds value.

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

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

For a simple two-parameter write tool with no output schema, description covers purpose, usage, persistence, and pairing with sibling tools completely.

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

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

Schema already covers both parameters with descriptions (100% coverage). Description adds example key patterns but no new semantics beyond the schema.

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

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

Description clearly states the tool saves data for reuse across conversations/sessions, distinguishing it from siblings recall and forget. Verb 'save' and resource 'data' are specific.

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

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

Explicitly says 'Use when you discover something worth carrying forward' with examples. Pairs with recall and forget, though no explicit '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 declare readOnlyHint and idempotentHint, and the description adds substantial behavioral context: ambiguous matches 'assert nothing' and return figi_candidates, unresolved identifiers are explicitly listed under `unresolved`, upstream GLEIF/OpenFIGI failures degrade gracefully, and each call cascades through multiple lookup endpoints. No contradiction with annotations.

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

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

The description is front-loaded with query examples and the primary directive, and uses labeled 'SUPPORTED TYPES' sections for structure. It is dense and occasionally run-on with many parentheticals, and some guidance is repeated between the description and the value parameter description, so it is not maximally 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?

Although there is no output schema, the description covers what gets returned per type, ambiguity behavior, unresolved fields, fallback behavior, and internal cascading. For a two-parameter read-only tool, the invocation context is essentially 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%, but the description goes well beyond the schema: it specifies accepted forms (ticker, CIK, ISIN, company name; brand/generic for drugs), gives examples, and warns that for bonds the value must be the exact issuer as printed and never a full noun phrase. This materially improves invocation correctness.

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 leads with concrete user-phrase examples and a clear statement: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It names the resources (CIK, ticker, LEI, FIGI, RxCUI) and explicitly says 'Use FIRST whenever you have a name but need an ID,' making its purpose distinct from sibling profile/research 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?

It gives an explicit when-to-use directive ('Use FIRST whenever you have a name but need an ID') and enumerates accepted input forms for both types. It does not explicitly name sibling tools to use instead in other scenarios, but the context is clear enough that an agent can route correctly.

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

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

Annotations already declare read-only, idempotent, and open-world behavior. The description adds value by detailing the process: probes each entity, ranks by score, and returns a ranked list with score, confidence, signal density. This goes 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 four sentences, each adding value. It front-loads the core purpose, then explains the process and use case, without any redundant or wasted words.

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

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

Given no output schema, the description adequately describes the return format (ranked list with score, confidence, signal density per entity). It covers the tool's context and process. Minor omission: no mention of potential errors or limitations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds that the first entity in the array is treated as the 'subject' for narrative, which enriches the meaning of the 'entities' parameter beyond the schema 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 verb 'Compare' and resource 'AI visibility across multiple entities'. It explicitly distinguishes from sibling tools by explaining it probes each entity with ai_visibility_check and ranks them, which is not done by the single-entity sibling.

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 a concrete example. However, it does not explicitly mention when not to use this tool or suggest alternatives like using ai_visibility_check individually, which would be 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?

Description adds concrete behaviors beyond annotations: fans out to two services, partial failures degrade gracefully, first measurement can be slow (5-30s), sources_failed list returned. No contradiction with annotations (readOnly, idempotent, etc.).

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

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

Single paragraph with all key info, front-loaded with main purpose. Slightly long but efficient; no wasted sentences. Could use bullet points for clarity but still 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, but description sufficiently lists return fields (summary block, per-advisory, links, alternative versions), covers error cases (timeout), and ecosystem scope. Adequate for agent to use correctly.

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

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

Schema coverage is 100%, so baseline 3. Description adds context: scoped packages accepted, defaults to latest version. Extra details improve understanding but are not critical.

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

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

Description clearly states the tool is a composite check for adding an npm package, covering license, advisories, version history, and bundle size. It distinguishes from siblings by specifying NPM-only in v1 and other ecosystems via deps.dev directly.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me". Also mentions limitations (NPM only), partial failure behavior, and alternative for other ecosystems.

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

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

Discloses key behavioral traits: uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, has a 200K char cap with truncation flagging, and returns character offsets. These details go well beyond the annotations (readOnlyHint, idempotentHint, etc.) and provide a clear understanding of tool operation.

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?

Compact 4-sentence paragraph, each sentence earning its place. Front-loaded with core purpose, followed by examples, usage guidance, and technical constraints. 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?

Despite no output schema, the description clearly states returns: top-N passages with character offsets and similarity scores. Covers input limits, truncation, and embedding details. Sufficient for an agent to understand and use the tool correctly.

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

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

Adds significant meaning beyond the input schema: describes 'text' as document to search, gives example queries for 'query', and specifies default and range for 'limit'. Schema coverage is 100% but description enriches each parameter with practical 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 defines the tool's purpose as semantic search inside a fetched record, with specific examples (SEC 10-K, article) and details about return values (passages, offsets, scores). It distinguishes itself from sibling tools like ask_pipeworx_grounded.

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

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

Provides explicit guidance on when to use this tool: 'Use when the record is too big to cram into the prompt.' It explains benefits (saves context, returns relevant passages) and mentions pairing with ask_pipeworx_grounded. Also notes input limits and truncation behavior.

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

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

The description discloses important behavioral details beyond annotations: delivery channel constraints (SMS verification, 10/day cap; webhook auto-disable on failures), one-time webhook secret, and the persistent feed always on. Annotations are consistent (not readOnly, not destructive, idempotent).

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 densely packed with valuable information, organized logically: purpose, requirements, type examples, delivery channels. Every sentence adds context without redundancy. It is front-loaded with the core action.

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

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

Given no output schema, the description covers the return value (subscription ID), all input parameters with examples, prerequisites, and delivery constraints. For a creation tool with 3 parameters, this is thoroughly 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?

Despite 100% schema coverage, the description adds significant value with concrete examples for each subscription type's params (e.g., sec_8k with ticker and items) and detailed delivery behavior (webhook signing, SMS verification). This goes well beyond the schema's brief descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe' by specifying 'create' and providing context about the subscription lifecycle.

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

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

The description provides explicit guidance on when to use the tool (for proactive monitoring) and includes prerequisites (Pipeworx OAuth account required, anonymous/BYO not supported). It does not explicitly state 'when not to use', but the context and sibling list imply 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, openWorldHint, idempotentHint, destructiveHint. The description adds context about return format (category-bucketed questions with tool/argument shapes) and that it draws from a 'live catalog of thousands of tools'. 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 thorough but slightly lengthy. It front-loads example queries and uses readable structure with parenthetical lists. Every sentence serves a purpose, though minor trimming for brevity could be done 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 simplicity (1 optional parameter, no output schema), the description fully explains the return format and use case. It also situates the tool among siblings as a first-use guide, providing complete context for an 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 has 100% coverage and describes 'topic' with string values. The description enriches this by explaining what each topic focus area entails (e.g., 'finance', 'pharma'), and clarifies the outcome of omitting the parameter. This provides practical 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 uses specific verbs and resources: 'returns category-bucketed example questions... each with the exact tool + argument shape'. It clearly distinguishes itself from siblings like 'ask_pipeworx' by stating it is the 'onboarding entry point' for new users.

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

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

Explicitly states when to use: 'when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also provides guidance on optional topic parameter: 'omit for a cross-category spread' vs. 'pass topic to focus'.

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

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

Annotations provide idempotentHint and destructiveHint. Description adds valuable context: ownership enforcement, soft-delete behavior ('deactivated not deleted'), and link to recent_alerts for historical 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?

Two efficient sentences: first states purpose, second explains constraints and side effects. No fluff.

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

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

For a single-parameter mutation tool with no output schema, description adequately covers purpose, parameter, behavior, and related tool (recent_alerts). Annotations fill remaining gaps.

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

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

Schema coverage is 100% with clear description of 'id' parameter. Description only restates 'by id' without adding new information beyond the schema.

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

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

Description uses specific verb 'Cancel' and resource 'subscription' with clear method 'by id'. It distinguishes from siblings like 'subscribe' and '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?

Explicitly states ownership constraint ('you can only cancel your own subscriptions'), indicating when to use and when not. Does not name alternative tools but context is clear.

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

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

Annotations already provide safety hints (readOnly, idempotent), and the description adds critical behavioral nuance: it defines the meaning of 'could_not_verify' as a failed check (not evidence), distinguishes 'unsupported' from inconclusive, and explains the two data paths. This goes well beyond the structured annotations and prevents misinterpretation of results.

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 each sentence earns its place—it covers usage, pathways, return values, and edge cases. It is front-loaded with user phrasing examples and a concise one-liner definition. Slightly verbose but justified by the tool's complexity and the absence of an output 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?

Given there is no output schema, the description thoroughly covers return values (verdict enum), evidence with citations, reasoning, and error semantics. It also explains how the tool handles different claim types. An agent would understand exactly what to expect and how to interpret results, making it complete for this 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% for both parameters, but the description enriches the semantics: it gives concrete examples for 'claim' and explains how 'tolerance_pct' overrides implied wording with a recommended range for hallucination detection. This adds actionable meaning beyond the schema descriptions.

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

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

The description clearly names the action ('natural-language claim verification') and the resource ('authoritative sources'), with explicit query patterns like 'Is it true that…' and 'fact check'. It distinguishes itself from sibling tools by focusing on verifying claims and mentioning it replaces 4–6 sequential calls.

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

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

The description gives explicit context: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also outlines the two internal pathways (SEC EDGAR for financial claims, grounded pipeline for others), but it does not name an alternative tool or explicitly state when not to use it, so it stops short of a 5.

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

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

The description outlines the return fields (line items, customer billing/shipping, payment method, totals, status), adding value beyond annotations which already declare readOnlyHint, idempotentHint, etc. 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 two sentences, front-loaded with the main purpose. It is concise but could potentially be slightly more compact. 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 the tool's low complexity (fetch by ID, 4 clearly described parameters, output schema exists), the description provides complete context: what the tool does, input requirements, and return content.

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

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

Schema description coverage is 100% with each parameter having a description. The tool description does not add meaning beyond the schema; it merely mentions 'numeric ID' which is already in schema (type: number). 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 tool description uses a specific verb ('Fetch') and identifies the resource ('single WooCommerce order by numeric ID'). It clearly distinguishes from sibling tools like 'woo_list_orders' (which lists multiple orders) and 'woo_get_product' (different resource).

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

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

The description does not provide any guidance on when to use this tool versus alternatives, such as 'woo_list_orders' for fetching multiple orders. No when-to-use or when-not-to-use information is included.

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. Description adds no behavioral context beyond return contents, which is adequate but minimal given annotation coverage.

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

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

Single sentence that front-loads the purpose and lists key return fields. No redundancy or wasted words.

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

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

For a simple get-by-ID tool with an output schema, the description covers the essential behavior and return fields. Does not explain error cases (e.g., invalid ID) but not required given annotations and 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?

Schema coverage is 100% with descriptions for all parameters. The description adds no parameter-specific meaning beyond confirming 'numeric ID', so baseline score of 3 is appropriate.

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

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

Description clearly states 'Fetch a single WooCommerce product by numeric ID' with a specific verb and resource, and lists return fields (name, description, price, etc.), distinguishing it from sibling tools like woo_list_products which fetch multiple products.

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

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

Implies usage for fetching one product by ID but lacks explicit guidance on when to avoid or alternatives. With siblings like woo_list_products, it could mention that this is for single products only.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, so the description's behavioral disclosure is minimal. It adds that the tool returns specific customer data and supports pagination, 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 concise sentences. First sentence states purpose, second details returns and pagination. No fluff, front-loaded, and 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 presence of an output schema and annotations, the description covers the essential functionality (list customers, return fields, pagination). It lacks mention of filtering or authentication, but these are in schema and annotations. Very adequate for a simple list tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds that per_page has a max of 100 and page is for pagination, but these are already detailed in the schema. No additional meaning 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 action (list customers) and specifies the returned fields (IDs, names, emails, order counts). It distinguishes from sibling tools like woo_list_orders or woo_list_products by focusing on customers.

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

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

The description does not explicitly state when to use or not use this tool versus alternatives. It implies usage for retrieving customer lists and mentions pagination support, but lacks explicit context or exclusion criteria.

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, indicating safe reads. The description adds value by specifying return fields (order IDs, totals, customer info, line items) beyond the annotations. No contradictions.

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

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

The description is a single, well-structured sentence that immediately conveys the tool's purpose and key features. Every word adds value, no redundancy.

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

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

Given the existence of an output schema, the description does not need to detail return values beyond what it provides. It mentions filtering and key output fields. Could mention pagination, but overall sufficient for a list tool with good annotations.

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

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

Schema description coverage is 100%, so all parameters are documented in the schema. The description adds minimal parameter-level value beyond noting optional status filtering. Baseline of 3 is appropriate.

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

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

The description clearly states the verb ('List'), resource ('WooCommerce orders'), and optional filtering by status. It distinguishes from siblings like woo_get_order (single order) and woo_list_products (products).

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 mentions optional status filtering but does not provide explicit guidance on when to use this tool vs alternatives (e.g., woo_get_order for a specific order). The context signals list siblings but the description does not address them.

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 cover safety (readOnly, non-destructive). Description adds authentication method (Basic auth with consumer key/secret) and describes return fields, providing useful context beyond annotations.

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

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

Two efficient sentences with no waste. Front-loaded with purpose and immediately provides key details.

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

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

For a listing tool with good annotations and full schema coverage, the description covers auth, returns, pagination, and required parameters, making it complete.

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

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

Schema covers 100% of parameters with descriptions. Tool description repeats pagination info but does not 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?

Description clearly states 'List products' with specific resource (WooCommerce store) and auth method. Distinguishes from sibling tools like woo_get_product, woo_list_orders by naming the resource.

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

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

No explicit guidance on when to use this tool vs alternatives. While the resource implies it's for listing products, it does not compare to woo_get_product or caution about pagination boundaries.

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