Woocommerce

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral details beyond annotations: it explains the scoring range (0-100), the default model, that the API key is passed straight through to anthropic.com, and the return structure (per-model {score, confidence, signals, raw_response} + combined view). 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 five sentences, each adding value. The first sentence defines the core purpose, the second details default and option, the third explains return structure, and the fourth gives use cases. No filler or redundancy. Information is front-loaded.

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

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

Given the tool has 4 parameters, no output schema, and annotations covering safety, the description is complete. It covers all parameter behaviors, return format, use cases, and cost implications (BYO key). An AI agent can correctly select and invoke this tool based on the description alone.

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. However, the description adds significant meaning: for 'models', it lists supported values and clarifies the default; for '_apiKey', it explains it's optional and only needed for Anthropic, and how it's used; for 'context', it explains purpose (disambiguation). This goes well beyond the schema's 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 probes LLMs for knowledge about a business/brand/product/topic and returns a visibility score per model. It uses specific verbs like 'probe' and 'score', and the resource (LLM knowledge about an entity) is unambiguous. The tool is distinct from siblings like 'ask_pipeworx' (which queries a specific knowledge base) and 'compare_entities' (which compares entities), so no 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 explicitly mentions default and optional models, the need for an API key for Anthropic, and lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It lacks explicit 'when not to use' guidance or alternatives, but context signals provide sibling tools for reference. The description effectively sets expectations for when to invoke this tool.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: it returns structured answers with citation URIs, is fast ('one fast call'), and routes across many tools. No contradictions with annotations.

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

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

The description is well-structured with a bolded priority statement, a bulleted list of use cases, and clear hierarchical guidance. It is slightly verbose but 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 tool's broad scope (4,927 tools across 1,293 sources), the description covers purpose, usage, behavioral traits, output format (citations), and tier availability. It also distinguishes from siblings and provides a default entry point, making it contextually 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 (question and aliases) described. The description adds natural language context but does not provide additional details 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: answering factual questions by routing to thousands of tools, and distinguishes it from sibling tools like ask_pipeworx_grounded and deep_research with specific guidance on when to use each. Examples of questions illustrate the scope.

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

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

The description explicitly tells the agent to prefer ask_pipeworx over web search, provides detailed examples, and specifies when to step up to alternatives ('for a hallucination-resistant single answer...' and 'for a broad/multi-part question...'). It also notes that breaking-news is already handled, reducing ambiguity.

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 extra LLM call cost, explicit refusal reasons, and that answers are extracted only from tool results. Annotations provide readOnlyHint, openWorldHint, idempotentHint; description adds significant behavioral context without 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?

Description is front-loaded with purpose and usage, each sentence adds value. Slightly verbose but clear and well-structured.

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

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

Fully explains return format (success and refusal), process, and parameter semantics. No output schema exists, so description compensates completely. All relevant context is covered.

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 applies. Description mentions aliases but adds minimal insight beyond what schema already provides for each parameter.

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 it's a 'Hallucination-resistant answer mode for high-stakes reads', explains the process of routing, tool selection, and extraction. It distinguishes from sibling ask_pipeworx by specifying the added extraction step.

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 use when answers will be quoted or acted on (financial, legal, medical, public statements) and recommends ask_pipeworx for casual lookups. Provides clear when-to-use vs alternative.

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

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

Annotations already indicate readOnly, idempotent, non-destructive behavior. The description goes far beyond, detailing resolution logic, fan-out examples, edge cases (low confidence, closed markets, wide spreads, cancellation rules), and response shapes. This provides exceptional transparency into all behavioral traits.

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

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

The description is quite lengthy (multiple paragraphs). It front-loads the core purpose, but subsequent sections could be condensed. The structure with clear sections helps, but overall wordiness reduces efficiency for an AI agent.

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 the tool (multi-step research, no output schema), the description thoroughly covers response structure, resolver contract, parent event extractor, news fields, safety mechanisms, and resolution-rule risk. It leaves no essential detail missing for an agent to correctly use and interpret results.

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

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

Schema coverage is 100% (all three parameters documented). The description adds value by explaining the 'depth' enum ('quick' vs 'thorough') with fan-out examples, and the 'include_raw' parameter with size implications and use cases. This goes beyond the schema descriptions, though not every nuance is covered.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). This is specific, actionable, and distinguishes the tool from vague alternatives.

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

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

The description provides usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' While it doesn't explicitly exclude other tools or compare to siblings, the context is clear. A slight improvement would be naming sibling tools to avoid, but the given guidance is strong.

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

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

The description adds significant behavioral details beyond annotations: it explains data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handles off-calendar fiscal years, returns sorted results with citation URIs, and notes efficiency gains. Annotations already indicate read-only, open-world, idempotent, non-destructive behavior, so the description enhances understanding.

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 example queries, making it easy to grasp the tool's purpose immediately. It is dense but each sentence provides unique information (data sources, return format, efficiency claim). A minor reduction in length could 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?

Given the absence of an output schema, the description covers return format (paired data, citation URIs, sorted) and input constraints (2–5 items, supported types). It is complete enough for an agent to use the tool correctly, though more detail on output structure could be beneficial.

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?

With 100% schema coverage, baseline is 3. The description adds meaning by explaining the 'type' parameter's options and what data corresponds to each, and provides examples for 'values' (tickers/CIKs for companies, names for drugs). This adds context beyond the schema's minimal descriptions.

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

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

The description clearly states it performs side-by-side comparisons of 2–5 companies or drugs in one parallel call, with specific verb phrases like 'compare X and Y' and 'rank these companies.' It also distinguishes from sequential lookups, making the purpose unambiguous.

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

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

It explicitly advises to prefer this tool over sequential single-pack lookups when comparing entities, and describes what data each type pulls. However, it does not mention scenarios where this tool should not be used or provide alternatives beyond sequential lookups.

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) are already positive, but the description adds rich behavioral context: time expectations (15-60s up to 90s), parallel decomposition, facet routing, output format (findings packet with evidence, confidence, gaps, contradictions), hop detail, and semantic excerpting. It 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?

The description is lengthy but front-loaded with critical info (account requirement, alternatives). Every sentence adds unique detail about behavior, output, or constraints. While slightly verbose, the complexity of the tool justifies the length.

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

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

Given the tool's complexity (multi-source research, parallel decomposition, rich output format) and lack of output schema, the description comprehensively covers all necessary aspects: how it works, output fields, limitations, prerequisites, alternatives, time estimates, and citation format. No gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value: for 'depth' it explains the behavior of each enum (quick=3 facets, standard=5+gap recovery+contradictions, thorough=8+full iterative hop+contradictions), and for 'question' it emphasizes that broad/multi-part questions are fine. This exceeds simple schema descriptions.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1293 STRUCTURED data sources...in ONE call'. It distinguishes from siblings like ask_pipeworx and explicitly contrasts with open-web search. The verb 'decomposes' and resource 'structured data sources' provide specificity.

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

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

The description provides extensive guidance: when to use (broad/multi-part questions), when not to use (single lookup use ask_pipeworx, breaking news prefer ask_pipeworx), prerequisites (account required, paid plan for thorough), and explicitly names alternatives with rationale. It also advises on second-hop iteration 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?

Annotations already indicate readOnlyHint=true and destructiveHint=false. Description adds that it returns full input schemas with curated examples, ready to call directly, and that it returns top-N results (default 20, max 50). Aligns with annotations and adds useful 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?

Single paragraph packs essential information (purpose, usage, examples, return details) without excess. Front-loaded with purpose. Could be slightly more structured (e.g., bullet points) but is 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 role as a discovery mechanism, the description covers when to use, what it returns, and examples. No output schema, but description adequately explains the return (top-N tools with schemas). Sufficient for 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 description coverage is 100%, but description adds value by listing aliases for 'query' (task, q, description, search) and providing example queries. This clarifies the natural language format 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?

Description clearly states the tool finds/returns relevant tools based on a task description, and distinguishes it from sibling tools by noting it should be called first to see the option set. The verb 'discover' and resource 'tools' are explicit.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Also lists example use cases (SEC filings, FDA drugs, etc.) indicating when it is applicable. Does not explicitly exclude cases, but the guidance is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds context: it fans out across multiple sources, includes a sunset notice for USPTO PatentsView API with soft-fail behavior, and explains data sources. No contradiction with annotations.

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

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

The description is dense and informative but somewhat verbose with a long list of example queries at the start. Could be more structured or condensed 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 no output schema and multiple data sources, the description comprehensively explains return fields, fallback behaviors, and dependencies. It covers what the tool returns and its limitations, making it complete for agent invocation.

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

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

Schema covers 100% with descriptions for type and value. Description adds examples and constraints (e.g., ticker or CIK, names not supported). No additional meaning needed beyond what's 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: 'full cross-source profile of a US public company in ONE parallel call'. It lists specific data sources and return fields, and is easily distinguishable from siblings like resolve_entity and compare_entities.

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 preference over chaining single-pack lookups for holistic views. Also clarifies that names are not supported and recommends using resolve_entity first if only a name is available.

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

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

Annotations already provide destructiveHint=true, idempotentHint=true. Description confirms delete action but adds no additional behavioral context beyond annotations. No contradiction.

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

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

Two sentences, front-loaded with action and usage guidance. No redundant information. Highly efficient.

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

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

Simple tool with one required parameter and no output schema. Description covers purpose, usage, and relationship with siblings. Fully adequate.

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 'key' with schema description 'Memory key to delete'. Schema coverage is 100%, so description adds no extra meaning beyond the schema. Baseline 3 applies.

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

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

Clear verb+resource: 'Delete a previously stored memory by key.' It also contextualizes usage with 'context stale, task done, clear sensitive data' and distinguishes from siblings 'remember' and 'recall'.

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

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

Explicitly states when to use (context stale, task done, clear sensitive data) and pairs with related tools. Lacks explicit 'when not to use' but provides sufficient 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 (readOnlyHint, idempotentHint, etc.) are complemented by description details on fetching, extracting, and emitting standard format. No contradictions.

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

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

Description is concise with two sentences plus a list; front-loaded with key action and purpose. Could be slightly more structured but overall 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?

Output is described as a single text blob; no output schema needed. With good annotations and moderate complexity, it is adequately complete.

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

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

Schema coverage is 100% and includes default/max for max_links. Description adds no extra meaning beyond schema, meeting baseline.

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

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

The description clearly states the verb 'Generate', the resource 'llms.txt file', and the purpose for AI crawlers. It distinguishes from sibling tools like ai_visibility_check by focusing on file generation.

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 site indexing, personal project drafting, competitor auditing), but does not explicitly state when not to use or mention alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds minimal behavior beyond listing return fields. No contradiction.

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

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

Two concise sentences, front-loaded with purpose, each sentence provides essential information without redundancy.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description completely covers purpose, usage, and return fields.

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 parameter include_inactive with full description (100% coverage). Description does not add extra 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?

Clearly states it lists the caller's active subscriptions and enumerates returned fields (id, type, params, etc.). Distinguishes from sibling tools like subscribe/unsubscribe.

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

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

Explicitly advises when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Provides clear usage context.

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

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

The description discloses rate limits (5 per identifier per day), that it is free and doesn't count against quota, and how feedback is used ('team reads digests daily and signal directly affects roadmap'). Annotations show readOnlyHint=false, destructiveHint=false, etc., and description 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 well-structured and efficient. It starts with the core purpose, then explains the categories of use, provides a 'don't' rule, explains team usage, and ends with rate limit and free nature. 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 3 parameters with 100% schema coverage, no output schema, and a nested object, the description covers all necessary aspects: usage, context, constraints, and behavior. It does not need to explain return values for a feedback 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 baseline is 3. The description adds meaningful guidance beyond the schema: for 'type' it expands on each enum value, for 'message' it instructs to be specific with tool/error/data. This extra context justifies a 4.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses specific verbs like 'tell' and 'use when,' and distinguishes itself from sibling tools (none of which are for feedback).

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

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

Explicit usage guidance is provided: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also advises what not to include ('don't paste the end-user's prompt') and mentions rate limits and free usage.

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

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

The description adds significant behavioral context beyond annotations: data source (CF analytics-engine), no PII, caching window (5min-1h). Annotations already declare idempotent and read-only, and description aligns perfectly.

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

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

Description is concise, front-loaded with core function, and uses bullet points for use cases. Every sentence adds value with no redundancy.

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

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

Despite no output schema, the description adequately covers what the tool returns. However, a brief note on the output format (e.g., list or JSON) would improve completeness.

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

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

Schema coverage is 100% and description adds meaningful nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enhances understanding beyond 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 recent windows. It also provides three specific use cases, making the purpose very clear and distinct from 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 explicitly lists three use cases, but does not mention when not to use the tool or alternatives. However, the use cases are concrete and guide appropriate usage.

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

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

Despite annotations already indicating readOnlyHint, openWorldHint, and idempotentHint, the description adds rich behavioral context: monotonicity checks, partition_sum logic, Jaccard similarity anchor, placeholder filtering, fill check with CLOB depth, and practical trade advice (do not trade if realizable_edge_pp ≤ 0).

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 and densely detailed, but well-organized with clear sections for each mode and important sub-components (semantic anchor, partition filter, fill check). Every sentence adds value, though some technical details could be condensed 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 missing an output schema, the description fully explains the response structure (opportunities[] with fields, partition_check) and covers edge cases (skipped_low_similarity, placeholders filtered, thin_legs). For a complex analysis tool, this is comprehensive.

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

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

Schema coverage is 100% with basic descriptions, but the description adds significant value by explaining what each parameter does in practice (event slug vs topic seed question), providing concrete examples, and differentiating the modes. This far exceeds baseline.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two explicit modes (event and topic) plus a default trending_scan, making the purpose specific and distinct from sibling tools.

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

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

Provides explicit when-to-use guidance for each mode ('Call with NO args...', 'event (recommended for a specific market)', 'topic for a themed cross-event scan') and refers to a sibling tool for custom sizing, covering both selection criteria and exclusion context.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses caching at 1h, KV-keyed on all knobs, the Fed bets exclusion from ranking with a note why, and detailed response structure including diagnostics that explain why segments may be empty. This provides comprehensive 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 quite detailed and structured with sections for segments, knobs, and response. It front-loads the purpose but includes verbose model explanations (e.g., lognormal barrier, GDELT) that may be excessive for an agent. Shortening some technical details could improve conciseness without losing key usage information.

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

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

Given 9 parameters (all schema-described) and no output schema, the description fully explains the response structure: by_segment with three segments, fields per opportunity (edge_pp_net, kelly_fraction, liquidity, spread, volume, 24h-move warning), diagnostics, and caching. No missing context for correct invocation or interpretation of results.

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

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

Schema coverage is 100%, baseline 3. The description adds meaningful context beyond schema for parameters like min_kelly ('Skips opportunities that are too small to bet sensibly'), slippage_pp (explains zero fees but typical spread), and min_partition_leg_kelly (explains why partition arbs need a separate knob). This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: scanning Polymarket markets for opportunities where Pipeworx data disagrees with market price, explicitly targeting 'what should I bet on today'. It details three specific model families, distinguishing the tool from siblings like polymarket_arbitrage through its unique data source and methodology.

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 extensive guidance on when to use the tool and how to adjust knobs like min_liquidity, max_spread_pp, and min_kelly to filter tradeable edges. It explains what to do if a segment is empty via diagnostics. However, it lacks explicit comparison to sibling tools for when to choose this over 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 readOnly, openWorld, idempotent, and non-destructive. Description adds meaningful behavioral details: reads from snapshots, 60-day TTL, decay from daily closes not intraday, snapshot availability on cache-miss. 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 comprehensive but lengthy and dense with technical jargon. It front-loads the core purpose but could be more concise for an AI agent.

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 (tracked, expired, snapshot_dates) with field meanings. This is essential for a complex tool and compensates fully for the missing 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 coverage is 100% with descriptions. The tool description adds the default values and clamps for 'days' (2-30) and default for 'window' (1wk), which go beyond schema.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily snapshots, answering the question about edge age and trend. It distinguishes itself from sibling tool polymarket_edges by explicitly being built from its snapshots and focusing on historical persistence.

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

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

The description explains when to use it (to assess edge age and decay) and provides context (fresh vs old wide edges). It implies the alternative (polymarket_edges for current edges) but does not explicitly state when not to use it or list 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=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: walking the ladder, returning fields like slippage_pp and verdict, and highlighting that partial basket fills convert an arb into an unhedged directional position (the dominant loss mode). This extra detail merits a score above baseline.

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 fairly long but well-organized with clear section headers (SINGLE-MARKET, BASKET). Every sentence contributes information; no filler. However, it could be slightly more concise by combining some repetitive phrasing, but overall it's well-structured and front-loaded with the core purpose.

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

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

Given the tool's complexity (two modes, four parameters, no output schema), the description is remarkably complete. It explains both modes in detail, lists all return fields for each, and covers edge cases (thin legs, forced directional risk). The absence of an output schema is fully compensated by the return field descriptions.

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 nuance beyond the schema by explaining the dual interpretation of size_usd (max spend on buys vs target proceeds on sells) and the auto default for basket side logic. It also clarifies the 'settlement notional' concept for basket mode, improving understanding.

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 starts with a clear verb-resource pair: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It immediately distinguishes single-market and basket modes with specific details, setting it apart from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable on thin books, partial fills create directional risk), providing clear context for tool selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds rich behavioral details: two modes, response structure (leg-by-leg prices, spread, compatibility_warning, temporal_alignment), and counters for skipped cross types. It also explains the two cases that trigger compatibility_warning and what temporal_alignment means.

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 headings (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. It is somewhat lengthy but every sentence adds value. Could be slightly more concise but remains effective.

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

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

With no output schema, the description fully explains the response including spread, safety fields, and temporal alignment. It covers all parameter behaviors, modalities, and warnings comprehensively. No gaps for an agent to understand the tool's output and constraints.

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

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

Schema coverage is 100% (all three parameters documented). The description adds significant meaning: lists all topic options, explains that explicit params override mapped ones, and provides examples. This goes well beyond the schema alone.

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

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

The description clearly states it computes a cross-venue spread between Kalshi and Polymarket for the same resolving question. The verb 'Cross-venue spread' is specific and distinguishes it from sibling tools like polymarket_arbitrage (intra-platform) and bet_research (generic research).

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

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

The description explains two modes (topic shortcuts and explicit pairing) and provides extensive guidance on when the tool yields results or warnings. However, it does not explicitly contrast with sibling tools or state when not to use it, though it cautions that most pre-mapped topics are not tradeable.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds context on scoping (anonymous IP, BYO key hash) and behavior when key omitted (list all), which enhances transparency without 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?

Four concise sentences, front-loaded with action, no wasted words. Every sentence adds value: purpose, usage, scope, and pairing instructions.

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 explains return behavior (value or list of keys). With simple retrieval and good annotations, it provides sufficient context for correct invocation, though return format is not specified.

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

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

Schema covers the single parameter with 100% description. The description adds 'omit to list all keys', reinforcing the optional nature and providing clear usage 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?

Clearly states 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' The verb and resource are specific, and it distinguishes from siblings 'remember' and 'forget'.

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

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

Provides explicit when-to-use: 'to look up context the agent stored earlier' with examples (ticker, address, notes). Also contrasts with alternatives: 'Pair with remember to save, forget to delete.' and notes scoping.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds meaningful context: explains that 'mark_read:true' flags events read affecting subsequent calls, and that polling is safe. This goes beyond annotation-only disclosure.

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

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

Three sentences, each purposeful: first states purpose, second details returned fields, third lists filters and key behavior (mark_read) plus an alternative access note. No superfluous words, front-loaded with 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 5 optional parameters, no output schema, and safety covered by annotations, the description explains returned fields and key parameter effects. It mentions polling suitability and an alternative GET endpoint. Slightly missing explicit interaction between 'mark_read' and 'unread_only' (e.g., can they be combined?), but overall sufficient for effective invocation.

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

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

Schema description coverage is 100%, so the schema already documents all 5 parameters. The description adds value by explaining the purpose of filtering by type (e.g., 'sec_8k'), clarifying 'since' as ISO timestamp, and detailing the effect of 'mark_read' and 'unread_only'. It also mentions the returned fields, which helps agents understand what parameters influence output.

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 'pull fired events from your subscription feed' with specific verb and resource. It mentions the returned fields (source, citation_uri, raw event payload). While it implicitly distinguishes from siblings like 'list_subscriptions', it does not explicitly differentiate or name alternatives.

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

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

The description notes that 'polls work fine' and provides an alternative GET endpoint for scripts/dashboards, implying context of use. However, it does not explicitly state when to use this tool versus alternatives (e.g., when to use 'list_subscriptions' or other tools), nor does it provide when-not-to-use guidance.

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

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

The description fully discloses the tool's behavior: fans out to multiple sources (SEC EDGAR, GDELT/GNews fallback, USPTO), explains fallback logic, notes USPTO soft-fail, and describes return structure. This complements the annotations (readOnlyHint, etc.) without 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 appropriately sized for the tool's complexity. It front-loads the purpose, then details sources and fallbacks, then parameter usage, and ends with the alternative tool. Slightly verbose but 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 complex tool with multiple sources, fallbacks, and data aggregation, the description is very complete. It explains the return structure (changes[], total_changes, citation URIs) despite no output schema. All key behaviors are covered.

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 parameter descriptions. The description adds semantic value by explaining the fan-out behavior, date examples (ISO, relative), and acceptable values for type (company only). It enriches the schema but does not compensate for missing parameters.

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 provides a change feed for a company covering SEC filings, news, and patents. It distinguishes itself from the sibling entity_profile by explicitly contrasting static vs. dynamic use cases.

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

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

It provides explicit guidance on when to use (queries about what's new, latest, changes over time) and when not to (use entity_profile for static profile). The description also gives example query phrasings.

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

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

Annotations provide idempotentHint=true, readOnlyHint=false, destructiveHint=false. The description adds valuable behavioral context: scoped by identifier, authenticated users get persistent memory, anonymous sessions have 24-hour retention. No contradictions, but could also mention that writing to an existing key overwrites it (though implied).

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 with no wasted words. The most critical information is front-loaded (purpose and usage). Each sentence adds essential detail, and the structure flows logically from purpose to usage to behavior.

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

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

For a simple key-value storage tool with no output schema, the description is complete. It covers purpose, usage guidelines, parameter semantics, authentication, retention, and links to sibling tools. No gaps are apparent.

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 both parameters already described. The description adds examples (e.g., 'subject_property', 'target_ticker') and clarifies that value can be 'any text', adding meaning beyond the schema's basic type 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 the tool's purpose: 'Save data the agent will need to reuse later.' It specifies the resource (key-value pair) and the intent (reuse across sessions). It effectively distinguishes from sibling tools like recall and forget by mentioning them as complementary actions.

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

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

Explicit guidance on when to use: 'when you discover something worth carrying forward' and 'so you don't have to look it up again.' It also explains scoping (by identifier), persistence differences (authenticated vs. anonymous), and pairs with recall and forget for complete memory lifecycle management.

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

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

Annotations declare readOnly, idempotent, openWorld. The description adds: input flexibility (ticker, CIK, name for company; brand/generic for drug), auto-disambiguation, return fields (ticker, CIK, company_name, citation URI for company; RxCUI, ingredient, brand, citation for drug), and internal cascading lookups. No contradictions. Minor gap: no rate limits, but overall adds significant 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?

Well-structured with example queries leading, then purpose statement, then SUPPORTED TYPES in clear format. Front-loaded and efficient. Slightly lengthy due to detail, but earns its place without unnecessary words.

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

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

No output schema exists; the description fully compensates by detailing return data for each type (fields, citation URIs). Covers input flexibility, internal mechanics (cascading lookups), and disambiguation. Complete for the complexity of two entity types.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches both parameters: for type, it lists the two values; for value, it specifies acceptable inputs per type with examples and mentions auto-disambiguation for company. This adds meaningful context beyond the schema.

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

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

The description clearly states the tool resolves names to canonical identifiers with specific verb 'resolve' and resource 'name to canonical/official identifier'. It provides concrete examples and distinguishes itself as the primary tool for ID resolution among siblings via 'Use FIRST'.

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

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

Explicit usage guidance is provided: 'Use FIRST whenever you have a name but need an ID'. Example queries demonstrate when to invoke. Lacks explicit exclusions or comparisons to alternatives like entity_profile, but the directive is strong and clear.

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

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

The description discloses behavioral traits beyond annotations: it probes each entity with 'ai_visibility_check', ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, and signal density per entity. Annotations already declare the tool as read-only, idempotent, non-destructive, and open-world, which matches this behavior.

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

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

The description is two sentences plus an example, front-loaded with the main action. Every sentence adds value, with no fluff or repetition of schema details. It is appropriately sized and efficiently 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 has 4 parameters, no output schema, and no nested objects, the description conveys the output format (ranked list with score, confidence, signal density) and explains the probe mechanism. This is sufficient for an agent to understand what the tool returns and how it works.

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% description coverage, so baseline is 3. The description adds value by explaining that the first entity is treated as the 'subject' for narrative and that 'context' disambiguates common names. It also clarifies the role of 'models' and '_apiKey' parameters. This additional meaning justifies a score above baseline.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (compare) and resource (AI visibility), and distinguishes itself from the sibling tool 'ai_visibility_check' by emphasizing multi-entity comparison versus a single check.

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: 'Useful for competitive AI-marketing audits' and gives an example question. It implies when to use (comparing multiple entities) but does not explicitly state when not to use or point to alternative tools. However, the sibling list includes 'ai_visibility_check' as a single-entity alternative, which is not mentioned in the description.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds significant transparency about partial failure degradation, timeout expectations (5-30s), and the fact that sources_failed will list timed-out sources. 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?

A single dense paragraph that front-loads the purpose. While every sentence adds value, the description could be more structured (e.g., bullet points) for clarity. However, it is 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?

Despite no output schema, the description lists all return fields (is_latest, license, etc.) and explains failure behavior comprehensively, making the tool's outputs and constraints fully clear for agent 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 coverage is 100% with descriptions for both parameters. The description adds minor value (e.g., scoped packages accepted for 'package' and default behavior for 'version'), but does not substantially enhance 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?

Description explicitly states the tool is a composite check for deciding whether to add an npm package, listing the specific sources (deps.dev and bundlephobia) and the kind of data gathered. It clearly distinguishes from sibling tools by focusing on npm package evaluation.

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

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

Provides explicit when-to-use guidance ('is X safe / popular / small') and when-not-to-use ('NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly'), with an alternative mentioned.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds critical details: it uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, has a 200K character cap with truncation and flagging. This goes well beyond the annotations to inform the agent of internal mechanics and limits.

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

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

The description is concise, with five sentences that efficiently convey purpose, use cases, technical details, and limits. Information is front-loaded: first sentence states what it does, second gives when-to-use, third details output, fourth pairs with sibling, fifth adds technical specifics. No superfluous text.

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

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

Given the tool's moderate complexity, no output schema, and many sibling tools, the description is thorough. It covers purpose, usage context, behavioral specifics (embeddings, chunking, cap), output characteristics (offsets, scores), and integration with ask_pipeworx_grounded. The agent has enough to decide when and how to use it correctly.

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

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

Schema coverage is 100% with good parameter descriptions. The description adds value by providing example queries ('supply-chain risk', 'fiscal year 2024 revenue') and stating the default limit (5). It also explains that returned passages include character offsets, which is useful for verification. However, the core semantics are already captured in the schema, so the description is helpful but not essential.

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

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

The description clearly states the tool performs semantic search within a provided text record, using vivid language like 'INSIDE a fetched record' and specifying the output (passages with offsets and scores). It distinguishes itself from siblings by mentioning pairing with ask_pipeworx_grounded and emphasizing the ability to search inside fetched records rather than performing other operations.

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 recommends using this tool when a record is too large for the prompt, stating it 'saves context' and 'returns only the passages that matter.' It also provides guidance on how to pair it with ask_pipeworx_grounded, detailing a workflow: fetch via gateway, then ground over relevant passages. This gives clear when-to-use and complementary tool advice.

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 idempotentHint=true, but the description does not mention idempotency. However, it adds significant context: requires OAuth, details on delivery channels, SMS cap, webhook auto-disable, and response includes subscription ID. 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 densely packed with useful information, front-loaded with purpose and followed by type and delivery details. No superfluous 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?

The description covers purpose, types, delivery, and constraints. It lacks mention of error cases or idempotency behavior, but for a subscription creation tool with no output schema, it is largely complete.

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

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

Schema coverage is 100%, and the description provides detailed examples for each subscription type and delivery option (e.g., phone verification, 10/day SMS cap, webhook signing). This adds meaningful context beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes from siblings like list_subscriptions and unsubscribe by detailing subscription types and delivery channels.

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 specifies when to use the tool (creating subscriptions) and when not (anonymous, BYO accounts). It lists supported types and delivery channels, but does not explicitly guide when to choose this tool over alternatives like list_subscriptions or unsubscribe.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds that it draws from a live catalog and returns categorized examples. No hidden behaviors disclosed beyond annotations.

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

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

Description is front-loaded with trigger phrases and then provides structured details. While slightly long, it is well-organized with category lists and no unnecessary sentences.

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

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

No output schema, but description fully explains return format (category-bucketed examples with tool+argument shapes). Complete for an onboarding tool with good annotation coverage.

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. Description adds value by listing example topics and explaining that omitting topic gives full spread.

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

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

The description clearly states the tool returns category-bucketed example questions with exact tool+argument shapes. It distinguishes itself from sibling tools like ask_pipeworx by being the onboarding entry point.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides context for optional topic filtering. It also mentions learning how to call meta-tools.

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

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

Beyond annotations (idempotent, not destructive), the description adds that ownership is enforced, the row is deactivated not deleted, and historical events remain accessible via recent_alerts. This provides crucial 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 three sentences, front-loads the main action, and contains no redundant information. Every sentence adds value.

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

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

For a simple tool with one parameter and no output schema, the description covers behavior, ownership, data lifecycle, and references a related tool. No gaps identified.

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

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

The single parameter 'id' is fully described in the schema as 'Subscription id (uuid) returned by subscribe.' The description does not add further meaning beyond what the schema already provides, 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 uses the verb 'Cancel' and specifies the resource 'subscription by id'. The title clarifies it's for alerts. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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

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

The description states ownership enforcement and that cancellation is a deactivation, not deletion. It implies when to use this tool (to cancel own subscriptions), but does not explicitly mention when not to use or 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, and destructiveHint false. Description adds substantial behavioral context: returns a verdict with specific categories, structured form, actual value with citation, percent delta, and notes efficiency gain. No contradiction with annotations.

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

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

Description is a single, information-dense paragraph starting with usage examples. Slightly verbose but efficient; every sentence adds value. Minor improvement could be made by breaking into bullet points, but current structure is acceptable.

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 required parameter and no output schema, description covers return structure (verdict, extracted form, actual value, percent delta, citation) and underlying source (SEC EDGAR + XBRL). Sufficient for agent understanding; could mention error cases but not essential.

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 detailed description of the 'claim' parameter. Description reinforces this with examples, but adds no extra meaning beyond what the schema provides. Adequate for high schema coverage.

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's purpose: natural-language claim verification against authoritative sources, with specific example queries and domain (company-financial claims). It distinguishes itself from sibling tools by its unique functionality (fact-checking vs. general search or entity profiles).

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: 'whenever the agent needs to check whether something a user said is factually correct.' Provides domain limitation (company-financial claims) but does not explicitly list when not to use or alternatives, though siblings differ enough to avoid confusion.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, establishing safe behavior. The description adds value by detailing what the response includes (line items, billing/shipping, payment method, totals, status), which the annotations do not cover. No contradictions.

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

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

Two concise sentences: first states the action and condition, second lists key return fields. No redundant information. Front-loaded with the core purpose, making it easy to scan.

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

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

Given the simple nature of fetching a single order, the presence of an output schema (so return format is covered elsewhere), and comprehensive annotations, the description covers all necessary aspects: what it does, how it's identified, and what it returns. No apparent gaps.

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

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

Schema coverage is 100%, so the schema already describes all parameters. The description mentions 'numeric ID' aligning with the id parameter, but adds no new semantic detail beyond what the schema provides. 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 uses a specific verb 'Fetch' and identifies the resource as 'a single WooCommerce order by numeric ID', clearly distinguishing it from sibling tools like woo_list_orders (multiple orders) and woo_get_product (different entity). It also enumerates returned details (line items, billing/shipping, etc.), reinforcing its specific purpose.

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

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

The description implies usage for retrieving a single order by ID, but it does not explicitly state when to use this tool versus alternatives like woo_list_orders for multiple orders or woo_get_product for product data. No exclusion criteria or alternative suggestions are provided.

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

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

Annotations already declare readonly, idempotent, and non-destructive hints. The description adds value by specifying the returned fields (name, description, price, etc.) but does not detail error cases or rate limits. No contradiction with annotations.

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

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

Two sentences with no wasted words. The verb and resource are front-loaded. Every sentence adds essential information.

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

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

For a simple retrieval tool with an output schema, the description covers the essential functionality and return content. It is complete and well-suited for its 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 all four parameters. The description adds minor clarification ('numeric ID') but does not significantly enhance understanding beyond the schema. 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?

The description clearly states the verb 'Fetch', the resource 'single WooCommerce product by numeric ID', and the return content including specific fields. This distinguishes it from sibling tools like woo_list_products (list) and woo_get_order (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 implies usage for fetching one product by ID but lacks explicit when-not-to-use or alternatives. The context of sibling tools provides this indirectly, but the description itself does not mention alternatives like woo_list_products for multiple products.

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

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

Beyond annotations (readOnly, idempotent), the description adds pagination limits (per_page max 100) and return fields, aiding behavioral understanding.

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

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

Two sentences, front-loaded with main purpose, no unnecessary words. Efficient and well-structured.

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

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

For a simple listing tool, the description covers return fields, pagination, and credentials. With full schema annotations and output schema, it is complete.

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

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

With 100% schema coverage, the description adds marginal value by reiterating pagination parameters and their limits, but does not introduce new semantic information.

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

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

The description clearly states the tool lists customers, specifies returned fields (IDs, names, emails, order counts), and is distinct from sibling tools like woo_list_orders and woo_list_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?

No explicit guidance on when to use this tool vs alternatives like woo_get_order or woo_list_products. Usage is implied but not differentiated.

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, and destructiveHint, so the safety profile is clear. The description adds value by listing the output fields (order IDs, totals, customer info, line items) but does not disclose other behavioral aspects like pagination behavior, rate limits, or data freshness. With annotations doing heavy lifting, this is adequate but not exceptional.

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

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

The description is a single sentence with two concise clauses. It is front-loaded with the action ('List WooCommerce orders'), includes key options, and avoids any fluff. Every part is informative.

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

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

Given that output schema exists and schema coverage is 100%, the description does not need to explain return format in detail. It already mentions what is returned. It could mention pagination behavior (e.g., 'paginated with page and per_page') but the schema covers that. Overall, it is complete for a list tool with good 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 description coverage is 100%—each parameter has a description. The description only mentions status filtering and lists status values, which are already in the schema. It adds no new parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the action ('List') and resource ('WooCommerce orders'), specifies optional filtering by status, and enumerates returned fields (order IDs, totals, customer info, line items). This makes the tool's purpose unambiguous and distinct from siblings like woo_get_order (single order) or woo_list_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 implies usage for listing orders with optional status filtering, but it does not explicitly state when to use this tool versus alternatives (e.g., use woo_get_order for a single order). No guidance on pagination limits or when not to use it.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. Description adds useful behavioral details: pagination limits (max 100, default 20), returned fields (IDs, names, prices, stock status, type), and auth method. No contradictions.

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

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

Two sentences, front-loaded with purpose, no extraneous information. Every sentence provides 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 context (output schema exists, annotation richness), description adequately covers pagination, returned fields, and auth method. Could mention sorting or filtering options, but not required 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 coverage is 100%, so schema already describes all parameters. Description mentions per_page and page but doesn't add new meaning beyond schema. Auth parameters are only referenced as 'Basic auth', which adds minimal extra 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?

Description states 'List products from a WooCommerce store' with specific verb, resource, and context (Basic auth, pagination, returned fields). Clearly distinguishes from sibling tools like woo_get_product (single product) and woo_list_orders (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?

Description implies when to use (listing products with pagination) but does not explicitly state when not to use or suggest alternatives like woo_get_product for single product lookups. No contrasting with sibling tools.

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