Traject Ecommerce

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

Beyond annotations, describes default model cost, BYO key for Anthropic, and return structure. No contradiction with annotations.

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

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

Two efficient sentences with core action and return format front-loaded, no unnecessary 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?

Fully explains what the tool does, what it returns, and when to use it, despite no output schema.

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

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

Adds meaningful context to all parameters beyond schema, e.g., explaining entity scope and _apiKey usage. Schema coverage is 100%.

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 entity visibility and scores it, distinguishing it from sibling tools like entity_profile or amazon_product.

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

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

Describes use cases (AI-marketing audits, brand checks) and mentions default vs. Anthropic model, but does not explicitly list when not to use or alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds minor context about the Rainforest API key and example call, but does not disclose significant additional behavioral traits beyond what annotations cover.

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

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

The description is one sentence plus an example, front-loaded with the core purpose and key details. No wasted words.

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

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

Despite no output schema, the description lists returned fields (title, brand, price, etc.) and mentions the API key source. It could clarify optional parameters or error handling, but is sufficient for a simple lookup tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds an example usage but does not add essential meaning beyond what the schema provides.

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

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

The description clearly states the verb 'Get' and the resource 'Amazon product details by ASIN', and lists specific fields returned. It clearly distinguishes from sibling tools like amazon_search and amazon_reviews.

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 use when you have an ASIN and need product details, but does not provide explicit guidance on when to use this tool versus alternatives like amazon_search or amazon_reviews. No when-not-to-use or exclusion criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds the authentication requirement (API key) and lists return fields, but does not disclose pagination behavior 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?

Single sentence with a clear list of return fields and an example. No fluff. Front-loaded with the action and resource.

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

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

Given the tool's simplicity (3 parameters, no output schema but good annotations), the description covers purpose, return fields, and auth. It lacks details on pagination or result count, but this is acceptable for a straightforward read-only tool.

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

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

Schema covers all 3 parameters with descriptions (100% coverage). Description adds an example call with sample values, which provides additional context but does not significantly extend beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states 'Get customer reviews for an Amazon product by ASIN' and lists specific fields returned. Differentiates from siblings like amazon_product (product details) and amazon_search (search results) by focusing on reviews only.

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 usage context by mentioning the Rainforest API key requirement and an example call, but does not explicitly state when to use this tool versus sibling tools like walmart_reviews or amazon_product.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that it uses a Rainforest API key, which is crucial for usage. 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 plus an example. Every word serves a purpose, with no redundancy. Front-loaded with the key action and output.

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

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

Given the tool's simplicity and comprehensive annotations, the description covers the core functionality. It lists return fields and includes an example. Could optionally mention result limits, but not critical for this use case.

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 each parameter. The description reinforces this with an example demonstrating all parameters in context, adding practical usage information beyond the schema.

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

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

The description clearly states 'Search Amazon products by keyword' with specific verb and resource. It lists returned fields (position, title, ASIN, etc.), distinguishing it from sibling tools like amazon_product and amazon_reviews.

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 example shows how to call the tool. While it doesn't explicitly state when not to use it, the context of the name and siblings implies its scope. Clear usage guidance is provided via the example and API key mention.

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. The description adds valuable behavioral context: it routes across 5,529 tools, fills arguments, returns structured answers with pipeworx:// citation URIs, and works on every tier. This goes well beyond the annotation hints and includes 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 dense but efficient: front-loaded with the key directive, followed by supported data domains, example questions, and upgrade alternatives. Every sentence earns its place, and the structure is logical despite its 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?

Despite having no output schema, the description explicitly discloses the return format ('structured answer with stable pipeworx:// citation URIs') and behavior ('one fast call'). It also covers scope, alternatives, and even notes what happens for breaking-news, making the tool fully understandable without additional context.

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

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

Schema coverage is 100% with all 6 parameters documented as aliases for 'question', so the baseline is 3. The description adds meaningful semantic guidance with real-world examples and explicit scope ('factual question about real-world entities, events, or numbers'), which justifies a higher score.

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

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

The description clearly identifies the tool as a question-answering router for authoritative structured data, using specific verbs like 'routes', 'fills', and 'returns'. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, and includes concrete examples.

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 'PREFER OVER WEB SEARCH' guidance, lists trigger phrases ('what is', 'look up', 'get the latest'), and names alternatives with exact reasons: ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions. Also covers breaking-news explicitly.

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

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

Beyond the readOnly/openWorld/idempotent hints, the description discloses that candidate routing improvements may be enabled live, that no candidate is currently active, and that it always functions as a full router—never degrading to nothing. This adds meaningful context about the experimental nature and safety.

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 deliver all essential information with no filler. Slightly verbose in the first sentence, but every clause serves a purpose and the beta state is highlighted upfront.

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 fully covers the tool's role, its relationship to ask_pipeworx, the current inactive-candidate state, the comparison mechanism, and the fact it is a complete working router. Given the absence of an output schema, noting the same response shape provides sufficient 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?

The input schema already fully describes all six parameters (aliases for question) with 100% coverage. The description only says 'same arguments' as ask_pipeworx, which adds no new parameter-level meaning beyond the schema, so baseline 3 applies.

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

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

Clearly states it is the beta version of ask_pipeworx, an identical universal router with the same 5,529 tools and arguments. Distinguishes from ask_pipeworx as the experimental edge for testing candidate routing improvements.

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

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

Explicitly instructs to use it exactly like ask_pipeworx when wanting the newest routing, and notes that results are compared against the stable router. Also clarifies it is a full working router, not a fallback, and that it currently matches ask_pipeworx exactly.

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 thoroughly discloses behavioral traits: it returns a structured object with evidence and refusal reasons, enumerates all refusal categories, and explains the internal tool-selection and data-extraction process. This goes well beyond the annotations (readOnlyHint, etc.) by detailing success and failure modes.

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

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

The description is dense but well-organized: it front-loads the core purpose, then explains mechanism, output format, usage, and cost in a logical flow. While longer than ideal, every sentence contributes unique value, and the structure helps the agent parse the details.

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

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

Given the tool's complexity and absence of an output schema, the description covers everything needed: return format, refusal reasons, when to use, cost, and relationship to siblings. It is fully self-contained for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% for all six parameters, all documented as aliases for 'question,' so the baseline is 3. The description adds minimal parameter-specific meaning; it mentions that the tool 'fills arguments' internally but doesn't elaborate on the 'question' parameter beyond what the schema already states.

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

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

The description clearly states the tool's purpose as a hallucination-resistant answer mode for high-stakes reads, using specific verbs like 'extracts' and distinguishing it from siblings like ask_pipeworx. It further clarifies the unique behavior of using ONLY tool results, making the purpose unmistakable.

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

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

Explicit guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' It names the alternative (ask_pipeworx) and explains the trade-off (extra LLM call), clearly defining when to use this tool over others.

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

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

The description provides extensive behavioral details beyond annotations: fan-out process, classifier categories, resolver contract, parent event extractor, news field fallbacks, safety short-circuits for low-confidence matches and closed markets, wide-spread illiquidity notes, and resolution-rule risk. There is no contradiction with annotations.

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

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

The description is very long and verbose. While it front-loads the main purpose in the first sentence, it could be more concise and better structured. Many details could be condensed or organized into sections.

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, the description is remarkably complete. It covers input formats, output structure (market, analysis, evidence, resolver, parent event, news fields), multiple edge cases (low confidence, closed markets, wide spreads, cancellation rules), and safety mechanisms. No output schema exists, but the description compensates thoroughly.

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

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

Schema coverage is 100%, and the description adds significant meaning: for 'market', it explains that slugs, URLs, or question text are accepted; for 'depth', it defines 'quick' and 'thorough'; for 'include_raw', it explains the trade-offs between concise summaries and full payloads. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: '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). The tool's domain is unique among siblings, distinguishing it implicitly.

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

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

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides clear usage scenarios. However, it does not mention when not to use or offer alternatives among sibling tools, which would improve 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 indicate read-only, idempotent, open-world. Description adds details: pulls latest 10-K from SEC EDGAR/XBRL, handles off-calendar fiscal years, returns sorted by primary metric, includes citation URIs. No contradictions.

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

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

Description is front-loaded with triggers and key action, but longer than necessary. Every sentence adds value, though some redundancy could be trimmed. Still 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?

Despite no output schema, the description explains return format (paired data + citation URIs, sorted by primary metric). Covers both entity types. Complete for a 2-param 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% (both parameters described). Description adds meaning: explains 'type' enum values (company/drug) and 'values' format (tickers/CIKs for company, drug names). Also details data sources per type.

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 side-by-side comparisons of 2-5 companies or drugs, pulling specific financial data for companies and adverse-event/trial data for drugs. It distinguishes from sequential single-pack lookups by name.

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

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

Explicitly lists natural language triggers ("compare X and Y", "X vs Y", etc.) and instructs to ALWAYS PREFER over sequential lookups when comparing entities.

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

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

Beyond the read-only/idempotent annotations, the description discloses key behaviors: it never invents answers (gaps[] for unanswered facets), returns contradictions[] at standard/thorough depths, uses semantic excerpting, includes a resolvable pipeworx:// citation, and has latency expectations (15-90s). It also warns about empty gaps on open-world topics, which is critical for grounding user expectations.

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 dense with valuable operational details. Every sentence serves a purpose, yet the structure is a single dense block without formatting (bullets or headers), which could hurt scannability. Still, it earns its length given the tool's complexity.

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

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

With no output schema, the description fully explains the return packet (verbatim evidence, confidence, source, fetched_at, stable citation, gaps[], contradictions[], hop field) and error/edge behavior. It also covers account requirements, depth variations, latency, and caveats for open-world topics, making it self-sufficient for invocation and result interpretation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining that 'question' is meant for broad/multi-part queries and that 'depth' controls facet count, gap recovery, and contradiction scanning. It also contrasts with ask_pipeworx for single-lookups, further clarifying the intended use of the question 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?

The description clearly identifies the tool as a multi-source grounded research engine over Pipeworx's structured data sources, explicitly contrasting it with 'NOT open-web search' and singling out its parallel decomposition behavior. It distinguishes from siblings like ask_pipeworx, making its specific purpose unambiguous.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: use for broad/multi-part structured-data questions, but use ask_pipeworx for single lookups or breaking/current-news topics. It also provides account-tier prerequisites and states that if not signed in, ask_pipeworx should be used instead, along with depth-level recommendations.

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. Description adds that results are 'ready to call directly, no second schema lookup needed', which is useful behavioral context beyond what annotations provide.

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

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

Front-loaded with key purpose and usage. While the list of domains is lengthy, it is relevant for a discovery tool. Every sentence adds value; could be slightly more concise but not wasteful.

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 discovery tool with 6 parameters and no output schema, the description explains return format (top-N tools with names, descriptions, schemas, examples) and behavior. Complete enough for the agent to understand what to expect.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by explaining that 'query' accepts natural language, lists all aliases, and describes 'limit' max. Provides curated examples in the schema examples array, enhancing 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 clearly states the tool's purpose: finding tools by describing data or task. It provides extensive examples (SEC filings, financials, FDA drugs, etc.) and distinguishes it from sibling tools as the discovery/search tool.

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'. Provides clear context for when to use, but does not explicitly state when not to use 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. Description adds soft-fail for patents, up to 5 filings with URIs, fundamentals sorted by period_end DESC, news fallback from GDELT to GNews. 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?

Front-loaded with example trigger phrases. Bullet-style output list is clear but slightly verbose in patent soft-fail and acronym expansions. 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?

With no output schema, description fully explains return structure (filings, fundamentals, patents, news, LEI) with details like sort order, URIs, and fallback behavior. Covers all input constraints and limitations.

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

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

Schema coverage is 100% with both parameters described. Description adds extra context: 'type' is only company (others coming), 'value' should be ticker or zero-padded CIK with guidance to use resolve_entity for names. Adds value beyond schema.

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

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

Description uses specific verb 'provides full cross-source profile' and clearly distinguishes from siblings like resolve_entity (which handles names) and compare_entities. It lists exact outputs: CIK, filings, fundamentals, patents, news, LEI.

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: 'ALWAYS PREFER over chaining single-pack lookups when user asks for holistic view.' Also states when not to use: 'Names not supported — use resolve_entity first.' Covers fallback behavior for patents.

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 and idempotentHint=true. The description adds behavioral context about clearing sensitive data but doesn't disclose any further traits like immediate persistence or side effects.

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

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

Two sentences front-loaded with the action and purpose. Every word is necessary; no waste.

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

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

For a simple one-parameter destructive idempotent tool, the description is complete. It covers purpose, usage, and pairing with siblings. No output schema needed.

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

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

Schema coverage is 100% with the parameter 'key' described as 'Memory key to delete'. The description reinforces 'by key' but adds no additional meaning beyond the schema.

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

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

The description clearly states 'Delete a previously stored memory by key', providing a specific verb and resource. It distinguishes from sibling tools 'remember' and 'recall' by focusing on deletion.

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

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

The description gives explicit usage contexts: when context is stale, task is done, or clearing sensitive data. It also mentions pairing with remember and recall, guiding when to use this tool vs 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 provide rich metadata (readOnlyHint, idempotentHint, etc.). The description adds value by explaining the process: fetches page, extracts title/description/key links, emits standard markdown. No contradictions with annotations.

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

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

Three sentences, no filler, front-loaded with key action. Every sentence serves a purpose: what it does, how it works, use cases.

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 states output is a single text blob ready for site-root. Annotations cover all behavioral aspects. Parameter count is low and fully described. The tool is simple and the description is complete.

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

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

Schema coverage is 100%, so description doesn't need to over-explain. It complements by describing the URL parameter as 'Full URL' and max_links with default/max, and the description of extraction actions adds context beyond schema.

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

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

The description clearly states the tool generates an llms.txt file for a URL, with specific verb 'Generate' and resource 'llms.txt'. It distinguishes from siblings by focusing on this specific task, while siblings include unrelated tools like search, research, etc.

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

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

The description explicitly lists use cases: getting a client's site indexed, drafting for own project, auditing competitor. It implies when to use but does not explicitly exclude alternatives or state when not to use, though context makes it clear.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds value by specifying default behavior (active only) and exact return fields, beyond what annotations provide.

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

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

Two efficient sentences: first states purpose and output, second provides usage guidance. No unnecessary words.

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

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

Given the simple tool (one optional parameter, no output schema), the description covers purpose, usage, and key behavior fully.

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

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

Schema has 100% coverage for the single parameter. Description mentions include_inactive implicitly but adds no new semantic detail 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 the tool lists the caller's active subscriptions and enumerates return fields. Differentiates from sibling tools like subscribe and unsubscribe by focusing on listing.

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 using this tool to review subscriptions before adding more or to find an ID to cancel, providing clear context for when 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 only declare non-read-only, non-open-world, non-idempotent, non-destructive traits. The description goes well beyond this by explaining the claim_token return and follow-up flow, the daily rate limit of 5 per identifier, that feedback is free and does not count against tool-call quota, and how the team processes digests.

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

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

The description is long but every sentence carries distinct information: purpose, use cases, exclusions, return contract, rate limit, and quota. It is front-loaded with the core action, and while dense, it contains no filler. A slightly structured layout could improve readability, but each sentence earns its place.

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

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

Even though there is no output schema, the description fully specifies the return behavior (claim_token), the routing constraints, content guidance, and operational limits. The tool has moderate complexity, and the description addresses all aspects an agent needs to invoke it correctly 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%, so the baseline is 3. The description adds meaningful parameter context by explaining the claim_token lifecycle ('Filing without an account returns a claim_token; pass it back later') and by instructing that context should reference Pipeworx tools/packs rather than user prompts. This extra guidance lifts it 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 opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist' and enumerates feedback types (bug, feature/data_gap, praise), making the verb and resource explicit. It clearly distinguishes itself from sibling tools like ask_pipeworx and discover_tools by restricting scope to tools served by this Pipeworx connection.

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

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

The description gives explicit triggers: 'Use when a tool returns wrong/stale data (bug)... feature/data_gap... praise.' It also provides an explicit exclusion: if the tool came from a different MCP server, file it with that server instead. This is strong when/when-not guidance with 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 indicate read-only, idempotent, non-destructive. Description adds details: self-aggregating from CF analytics-engine, no PII, caching policy (5min-1h). 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?

Extremely concise: one sentence for purpose, bullet-like use cases, and technical notes. No redundancy, every sentence adds value. Well 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 no output schema, the description hints at return structure (top tools, top packs, total call volume) but lacks explicit format. However, the tool is simple and the description is sufficient for agent understanding.

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

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

Schema covers 100% of parameters with enum and description. Description adds value by explaining the trade-off between short and long windows ('Shorter windows surface what's hot right now; longer windows show steady-state demand'), enhancing understanding beyond the schema.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over recent windows, with specific time ranges. It distinguishes itself from siblings by focusing on aggregate trending signal, unlike other tools that retrieve specific data or perform searches.

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 three explicit use cases (discovering hot data sources, confirming canonical tools, aligning use case) and explains when to use different windows (short for hot trends, long for steady-state). No alternatives mentioned but the use cases are clear enough to guide 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 read-only, open-world, idempotent, and non-destructive. Description adds rich context: filtering (Jaccard similarity, placeholder drop), fill check mechanics, and response structure. No contradiction with annotations.

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

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

The description is lengthy but front-loaded with core purpose and modes. Every sentence adds value given the tool's complexity. Could be slightly more concise, but justified.

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

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

Covers all key aspects: three modes, partition filter, fill check, output structure. No output schema exists, so description compensates fully. Also references related tool for custom sizing.

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 mode-specific context, explains slug format and full URL acceptance for event, and describes cross-event scanning behavior for topic.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It explicitly distinguishes three modes (NO args, event, topic) and contrasts with siblings like polymarket_edges and polymarket_fill_risk.

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

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

Provides explicit guidance: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also explains when not to trade (fill check with 'do not trade it') and mentions polymarket_fill_risk as an alternative for custom sizing.

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

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

Annotations already declare readOnlyHint, openWorldHint, etc., but the description adds extensive behavioral details: caching at KV level for 1 hour, diagnostics like filter_skips, Fed candidates exclusion, and detailed segment logic. 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 front-loaded with purpose and well-structured into segments, knobs, and diagnostics. While lengthy, it packs necessary information without redundant sentences. Could be slightly more concise but appropriate for the complexity.

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

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

Given no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, diagnostics), parameter effects, and behavioral details like cache. All 9 parameters are covered in schema, and the description provides complete context for effective use.

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

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

Schema description coverage is 100% with detailed parameter descriptions. The description adds extra context beyond schema, such as how knobs affect segments and the meaning of response fields like edge_pp_net and kelly_fraction. This adds value 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 starts with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the tool's purpose and distinguishes it from siblings like polymarket_arbitrage by focusing on Pipeworx data.

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

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

The description explicitly states the use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' While it doesn't list alternatives, the context makes it clear when to use this tool. Sibling names provide implicit differentiation.

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, non-destructive), the description reveals behavioral traits: data from daily snapshots, cache-miss dependency, 60-day TTL, decay computed on daily closes not intraday, and handling of gaps. No contradictions.

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

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

The description is front-loaded with purpose, then organizes args, response, and limits. Every sentence contributes 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?

Despite no output schema, the description fully explains the response fields (tracked, expired, snapshot_dates) and their semantics, including edge_pp_net sign convention and trending logic. Covers limitations and data freshness.

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

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

Schema coverage is 100%, but the description adds meaning: defaults, max/min for days, snapshot family context for window, and explains response structure. Provides semantic 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: 'Edge persistence and decay telemetry' and answers 'how long has this edge existed and is it shrinking?' It distinguishes from siblings like 'polymarket_edges' by focusing on historical time-series and trend analysis.

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

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

The description provides clear context for when to use the tool, contrasting a fresh edge with a 3-week-old one. However, it does not explicitly name alternatives or state when not to use it.

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

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

The description details the tool's behavior beyond annotations: it walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns about forced directional risk and thin legs. No contradiction with annotations (readOnlyHint=true, etc.).

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

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

The description is well-structured with clear sections (SINGLE-MARKET, BASKET) and uses capitalization for emphasis. It is dense but every sentence adds value; could be slightly more concise but adequate for the complexity.

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

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

Given the absence of an output schema, the description thoroughly explains return values for both modes, covers edge cases (thin legs, forced directional risk), and provides examples of verdicts. It is comprehensive for a tool with 4 parameters and no output schema.

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

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

Despite 100% schema coverage, the description adds meaningful context for each parameter: defaults (size_usd=1000), auto-detection for side in basket mode, and differentiation between market and event parameters. This aids understanding beyond the schema.

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

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

The description clearly states the tool's purpose: a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes between single-market and basket modes, and uses specific verbs like 'check' and 'walks the ladder'.

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 this tool: before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. It warns about the dangers of partial fills and uncapturable theoretical overround, and names sibling tools (polymarket_arbitrage, polymarket_edges).

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, openWorldHint, idempotentHint, destructiveHint), the description adds extensive behavioral detail: response structure (leg-by-leg prices, spread array), safety fields (compatibility_warning, temporal_alignment, skipped counters), and explanation of when spreads are meaningful or not (non-equivalent bet shapes, temporal misalignment). It also notes that real spreads are rare, disclosing the tool's limitations.

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, starting with purpose, then modes, response, and safety fields. It is somewhat lengthy but each sentence adds necessary context about compatibility warnings and temporal alignment. The front-loading of key info ('Cross-venue spread...') is effective. Minor redundancy could be trimmed, but overall it's concise for the complexity.

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

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

Given the tool's complexity (cross-venue comparison with compatibility checks), 3 parameters, and no output schema, the description is remarkably complete. It explains the response structure (leg-by-leg prices, spread array), safety fields (compatibility_warning, temporal_alignment, skipped counters), and edge cases (non-equivalent bet shapes, semantic mismatches). No output schema is needed; the description suffices.

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% (3 parameters fully described), so baseline is 3. The description adds value by explaining the semantic distinction between 'topic' (pre-mapped macro shortcuts) and explicit parameters (kalshi_event_ticker, polymarket_event_slug), including the list of allowed topics. This helps the agent understand parameter 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?

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage by focusing on two-venue comparison. The verb 'Cross-venue spread' is specific and the description outlines two modes (topic and explicit), which differentiates it from other tools.

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

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

The description explains when to use each mode: topic for pre-mapped macros and explicit tickers for custom pairings. It warns that most pre-mapped topics return compatibility warnings, guiding the agent to expect limited tradeable spreads. However, it does not explicitly compare to alternatives like polymarket_arbitrage or give when-not-to-use instructions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds value by explaining scoping (anonymous IP, BYO key hash, account ID) and the listing behavior when key is omitted. No contradiction.

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

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

The description is well-structured with multiple sentences, each providing useful information. It could be slightly more concise, but it is not verbose and front-loads the main 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 the simple schema (1 optional param) and clear annotations, the description covers all relevant aspects: purpose, usage, scoping, pairing with siblings. It is fully adequate for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description restates the schema's parameter description but adds context about the types of values stored (e.g., ticker, address). This adds marginal 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 action (retrieve/list) and resource (saved values/keys). It explicitly distinguishes from siblings by naming remember and forget, making its purpose unambiguous.

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

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

The description provides concrete use cases (look up user's target ticker, address, research notes) and scoping information. While it doesn't list when not to use, the guidance is clear and actionable for an agent.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds rich behavioral details: the structure of returned events (source, citation_uri, raw payload), the effect of mark_read on subsequent calls, and polling suitability. 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 reasonably concise with front-loaded purpose. However, there is slight redundancy between 'Pull fired events' and 'Returns the most recent alerts'. Still, every sentence contributes useful 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?

Despite missing output schema, the description adequately explains what each returned event contains (source, citation_uri, raw payload) and the side effect of mark_read. It also provides an alternative access method for scripts and dashboards, ensuring completeness for agent decision-making.

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

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

While schema coverage is 100%, the description adds significant value by explaining each parameter's practical use: type filter with example ('sec_8k'), since as ISO timestamp, mark_read flag behavior, and unread_only flag. It clarifies semantics beyond the schema descriptions.

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

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

The description clearly states 'Pull fired events from your subscription feed' and specifies the exact resource and action. It distinguishes from sibling tools like 'recent_changes' and 'list_subscriptions' by focusing on alerts/events from the subscription feed.

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 tells when to use it (to fetch recent alerts) and that 'Polls work fine'. It also mentions an alternative HTTP endpoint for scripts and dashboards. However, it does not explicitly exclude other tools or provide comparative guidance against siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, but the description adds crucial behavioral details: it fans out to multiple sources (SEC EDGAR, GDELT→GNews, USPTO), explains fallback logic, notes a potential API sunset issue, and describes the return structure. 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 a single long sentence but packs a lot of information efficiently. It front-loads common query patterns. Could be broken into multiple sentences or bullets for readability, but every part earns its place.

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

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

Given no output schema, the description explains the return format (changes[] grouped by source, total_changes count, citation URIs). It covers multiple data sources, fallback behavior, and limitations. It's sufficiently complete for an agent to understand the tool's capabilities 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 description coverage is 100%, providing a baseline of 3. The description adds further meaning by explaining accepted formats for 'since' (ISO date or relative shorthand), clarifying that 'type' is currently only 'company', and that 'value' can be a ticker or CIK. This goes beyond the schema descriptions.

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

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

The description starts with example queries that clarify the tool's purpose, then explicitly states it is a 'change feed for a company'. It also distinguishes from the sibling tool 'entity_profile' by specifying when to use each, making the purpose very clear.

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

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

The description provides explicit usage guidance: it lists example queries for when to use, explains the fallback mechanism for news, and directly states when to use 'entity_profile' instead. This gives clear guidance on when to use and when not to use 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?

Beyond annotations (idempotentHint: true, destructiveHint: false), the description adds critical behavioral context: key-value pair storage, scoping by identifier, persistent memory for authenticated users, and 24-hour retention for anonymous sessions. This enhances the agent's understanding without contradicting the annotations.

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

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

The description is four sentences, front-loaded with the core purpose. Each sentence adds distinct value: primary action, usage trigger, storage details, and companion tools. No redundancy or filler.

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

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

Given no output schema, the description sufficiently covers intent, input, behavior, scope, persistence, and related tools. It leaves no major gaps for a simple key-value memory tool.

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

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

Both parameters have schema descriptions with examples, achieving 100% coverage. The description reinforces the key-value paradigm but does not add new details about parameter syntax or constraints 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 verb 'Save data' and the resource 'the agent will need to reuse later'. It distinguishes itself from sibling tools by naming 'recall' and 'forget' as companions, and provides concrete examples (resolved ticker, target address, etc.) to clarify 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 when to use the tool ('when you discover something worth carrying forward') and provides context about memory persistence (authenticated vs anonymous sessions). It also mentions alternative tools (recall, forget) for complementary actions, giving clear guidance on when to use each.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds substantial context: data sources (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), graceful degradation, explicit handling of unresolved identifiers, ownership information, and the cascading internal lookups. This goes far beyond annotation basics.

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 structured with example triggers upfront, a core purpose sentence, then type-specific details. It is verbose but every sentence contributes value (e.g., graceful degradation, source labeling). It could be tightened slightly but is still well-organized and 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?

For a 2-parameter tool with no output schema, the description is remarkably complete. It covers input formats, supported types, output characteristics (source labels, unresolved field), failure behavior, and even positions the tool as a time-saver. It addresses edge cases and gives concrete examples, fully compensating for the lack of an output schema.

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

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

Schema description coverage is 100%, with both parameters already well-described in the schema. The description repeats some parameter information (e.g., 'accepts ticker, CIK, or company name') but adds marginal detail like '10-digit CIK'. Since the schema carries the heavy lifting, this scores at baseline 3.

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

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

The description uses a clear verb ('resolve') and specifies the resource ('user-spoken NAME' to 'canonical/official identifiers'). It lists concrete example queries and explicitly distinguishes itself from siblings by stating 'Use FIRST whenever you have a name but need an ID' and noting that other tools require these identifiers as input.

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

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

Provides clear usage context with 'Use FIRST whenever you have a name but need an ID' and gives trigger examples. However, it does not explicitly name sibling alternatives or state when NOT to use this tool, so it lacks full exclusionary guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds behavioral details: probes each entity with ai_visibility_check, ranks by score, returns list with score/confidence/signal density. No contradictions.

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

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

Four sentences: purpose, mechanism, use case, return. No filler, front-loaded with action. Every sentence adds value.

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

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

No output schema, but description specifies return structure (ranked list with score, confidence, signal density). All parameters explained, no gaps given low 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%. Description adds beyond schema: 'entities' first entry is subject, numbers 2-8, and clarifies models behavior. Provides valuable context for selecting 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?

Description specifies a clear verb-comparison and resource-AI visibility across entities, distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison). Gives concrete example use case.

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

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

States 'Useful for competitive AI-marketing audits' and implies when to use (comparing multiple entities) vs single entity probing. Does not explicitly exclude alternative tools like compare_entities but provides enough context.

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

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

Annotations declare safety and idempotency; description adds critical behavioral details: partial failures degrade gracefully, bundlephobia first measurement takes 5-30s, sources_failed lists timed-out sources.

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, front-loaded, but slightly verbose; each clause 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?

Despite no output schema, description enumerates all return fields (summary block, advisory details, links, alternatives) and covers edge cases (partial failures, timing).

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

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

Schema already covers both parameters with descriptions; description adds useful context: scoped packages accepted, default version when omitted.

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 tool does npm package safety/popularity/size check via deps.dev and bundlephobia, contrasting with other tools for different ecosystems.

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

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

Explicitly tells when to use ('is X safe/popular/small', 'cost of adding lodash') and where not (other ecosystems go to deps.dev:version directly).

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 reveals key behaviors: embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), similarity metric (cosine), character cap (200K chars with truncation flag), and output format (offsets and similarity scores). This transparency fully informs the agent about expected 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 three sentences long, front-loaded with the core action ('Semantic search INSIDE a fetched record'), and every sentence contributes essential information. No redundancy or filler.

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

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

Given the complexity of the tool (semantic search over text, returning passages with offsets), the description covers all necessary aspects: input requirements, output format, use case, pairing with a sibling tool, technical details (model, chunking, cap). It leaves no ambiguity for an agent to misuse the 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?

With 100% schema coverage, the description still adds meaning: it clarifies that 'text' should be a fetched record (e.g., SEC filing, article), provides concrete query examples ('supply-chain risk'), and explains the 'limit' parameter as controlling the number of returned passages. This enriches 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 the tool's purpose: semantic search inside a fetched record, returning top passages with character offsets and similarity scores. It distinguishes itself from siblings by explicitly mentioning its complementarity with 'ask_pipeworx_grounded' and by highlighting its unique function of searching within an already-fetched text.

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

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

The description provides explicit usage guidance: 'Use when the record is too big to cram into the prompt.' It also explains how it pairs with ask_pipeworx_grounded. While it doesn't list explicit exclusions or alternatives, the context is clear and actionable.

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

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

The description contradicts the annotation idempotentHint: true by stating it 'creates' and 'returns new subscription id', implying non-idempotent behavior. This contradiction reduces trust.

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

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

The description is well-structured and front-loaded, but somewhat lengthy due to detailed examples. Still, every sentence contributes meaning.

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

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

Covers all types, delivery channels, prerequisites, and limitations. Lacks clarity on idempotency handling but is otherwise comprehensive for a subscription creation tool.

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

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

The description adds significant meaning beyond the schema, explaining type-specific params in detail and delivery options including webhook signing, phone verification, and rate limits.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns the subscription ID. It effectively distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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 creating subscriptions but does not explicitly state when to use this tool versus alternatives like list_subscriptions or recent_alerts. No when-not guidance is provided.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds clarity on how it behaves (returns example questions, can be filtered by topic). It could explicitly state it is a read-only query, but annotations cover that. No contradictions.

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

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

The description is thorough and front-loaded with common user queries. It uses clear structure with dash-separated categories. While slightly long, every sentence adds value. Could be slightly more concise, 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?

Even without an output schema, the description fully explains what is returned (category-bucketed example questions with tool+argument shape). It covers parameter behavior, the use case, and relationship to siblings. Complete for this tool's complexity.

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

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

Schema coverage is 100%, with a good description of the 'topic' parameter. The description adds contextual value by linking the parameter to use cases (e.g., 'pass topic to focus') and listing example categories. Schema already does heavy lifting, but description reinforces and adds purpose.

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

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

The description clearly states it is an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It uses specific verbs and resource description, and distinguishes itself from sibling tools like ask_pipeworx and discover_tools by suggesting to use it 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?

Explicitly tells when to use: 'the onboarding entry point for an agent that just connected' and gives explicit guidance on calling with no arguments for full spread or with topic for focus. It also mentions using it to learn how to call meta-tools, providing clear when-to-use context.

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

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

Provides rich details beyond annotations: ownership enforcement, soft-delete (deactivation instead of deletion), and retention of historical events via recent_alerts. 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 concise sentences front-load the primary action and immediately add critical behavioral nuance. No unnecessary words.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, behavior, and side effects. Could mention success/error response, but current information is sufficient.

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 already describes the id parameter as 'Subscription id (uuid) returned by subscribe.' The description adds 'Cancel a subscription by id,' which is helpful but does not significantly enhance semantic 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?

Clearly states the action (cancel), resource (subscription by id), and distinguishes from sibling tools like subscribe and list_subscriptions by noting ownership enforcement and soft-deletion behavior.

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

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

Describes when to use (cancel subscription) and a constraint (ownership enforced). Lacks explicit 'when not to use' or alternatives, but context is clear given sibling tool names.

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

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

Annotations already provide readOnly/openWorld/idempotent safety signals; the description adds substantial behavioral context beyond that: the meaning distinction between 'could_not_verify' (check did not happen) and 'unsupported' (no source covered), the verification_error structure, and the routing decision logic. This materially helps an agent interpret results correctly.

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

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

The description is longer than average but every sentence contributes: trigger phrases, use case, routing logic, return payload, failure semantics, and a caller warning. It is front-loaded with intuitive calls-to-action and uses clear structure (IMPORTANT) to highlight critical caveats without padding.

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

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

Given there is no output schema, the description fully covers the return contract (verdict values, actual value with citation, reasoning) and handles edge cases (could_not_verify vs unsupported). For a tool with high behavioral complexity and two routing paths, it is complete enough for an agent to invoke and interpret correctly without further documentation.

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

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

Schema coverage is 100% for both params, so the baseline is 3. The description adds practical nuance for tolerance_pct (e.g., 'set 1–2 for hallucination detection' and the default cap of 5) and clarifies that tolerance overrides the claim's implied wording, which goes beyond the schema text. Claim examples in the schema are adequate, so extra credit is modest.

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 specifies a distinct verb+resource: natural-language claim verification against authoritative sources, with explicit trigger phrases like 'fact check' and 'verify the claim that...'. It distinguishes itself from likely sibling tools by naming its two routing paths (SEC EDGAR/XBRL for company-financial claims vs grounded pipeline for all else) and by stating it replaces multiple sequential calls.

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

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

The description states exactly when to use: whenever the agent needs to check whether a user statement is factually correct, with both routing branches spelled out. It does not name alternative tools or explicit 'do not use' conditions, but the breadth of 'ANY OTHER factual claim' plus the claim-verification framing sufficiently sets expectations.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and no destructive behavior. The description adds that it uses a BlueCart API key and lists the returned fields. No contradictions; the description complements the annotations by specifying data source and output structure.

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 plus a code example. Every word adds value: it states the action, outputs, prerequisite (API key), and usage pattern. No fluff, front-loaded with the main verb.

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 lookup tool with no output schema, the description adequately lists the returned fields. The annotations cover safety and idempotency. The parameter descriptions and example are complete. No gaps remain for an agent to misuse this tool.

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

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

Schema coverage is 100% with both parameters described. The description adds a concrete example and notes that _apiKey is from BlueCart, including a hint about where to get it. This goes beyond the schema's basic description, providing usage context.

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

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

The description starts with 'Get Walmart product details by item ID', which is a specific verb and resource. It lists exact fields (title, brand, price, rating, ratings total, image). The name 'walmart_product' and inclusion among siblings like 'walmart_search' and 'walmart_reviews' clearly distinguishes it as a single-product detail tool.

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

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

The description explicitly says to use the item ID and API key, and provides an example. While it doesn't explicitly state when not to use it, the sibling tools (search, reviews) imply the context. A clear usage scenario is given: retrieving details by ID.

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. The description adds no new behavioral traits beyond the API key requirement. It does not mention side effects, rate limits, or other operational details, so it provides marginal additional value.

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

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

The description is extremely concise: a single sentence with a clear purpose, followed by a well-structured example. No redundant or unnecessary 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, read-only tool with two parameters and no output schema, the description adequately covers the return fields and how to call it. The tool is low complexity, and the description is complete given the 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% with both parameters described. The description adds an explicit example and a list of return fields (title, body, rating, date, verified-purchase flag), which provides semantic meaning beyond the schema descriptions alone.

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

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

The description clearly states the tool gets customer reviews for a Walmart product, listing the data fields (title, body, rating, date, verified-purchase flag) and providing an example. It distinguishes itself from siblings like amazon_reviews or walmart_product.

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

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

The description does not provide any guidance on when to use this tool versus alternatives, such as walmart_product or walmart_search. It only demonstrates how to call it with an example, lacking when-to-use or when-not-to-use context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description confirms read-only nature and adds return fields. No contradictions. Adds some value beyond annotations but not extensive.

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 plus an example. Front-loaded with purpose and return fields. No redundant 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?

With no output schema, description adequately explains return fields. Covers API key requirement and provides example. Missing pagination details but acceptable for a search 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 3. Description adds context: example usage and that API key is from BlueCart, providing extra meaning beyond schema properties.

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

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

Description uses specific verb 'search' and resource 'Walmart products', lists return fields (position, title, item ID, price, rating, ratings total), and distinguishes from siblings like walmart_product and walmart_reviews.

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 an example and mentions API key, implicitly suggesting when to use (search by keyword). Does not explicitly state when not to use or differentiate from alternatives, but context from sibling names helps.

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