Gtin

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds value by disclosing the scoring range, per-model output structure (score, confidence, signals, raw_response), combined view, and the billing implication for Anthropic (BYO key, pay Anthropic directly). 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?

Two detailed sentences efficiently pack the main purpose, default behavior, payment notes, and return structure. Front-loaded with key action and output. Could be slightly tightened but remains highly readable.

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 four parameters (entity, models, _apiKey, context), explains default vs paid models, output structure per model, and combined view. No output schema exists, but description compensates. Lacks error handling or limitations, but still 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?

With 100% schema description coverage, the description goes beyond by explaining default model behavior, the 'models' parameter options, the purpose of _apiKey (paid pass-through), and how 'context' disambiguates. It also describes the return format, which the schema lacks.

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 brand visibility and scores them 0-100, using specific verbs like 'probe' and 'score'. It distinguishes from siblings like deep_research or scan_competitor_ai_presence by focusing on per-model visibility scoring and specific use cases (AI-marketing audits, pre-launch brand checks).

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 the default model (free Workers AI) vs when to provide an API key for Anthropic. It lists concrete use cases (pre-launch checks, competitive monitoring) but does not explicitly exclude scenarios or compare to alternatives beyond the sibling list.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which assures safe read-only behavior. The description adds value by explaining that the tool routes to 4,500 tools across 1,137 sources and returns structured answers with stable citation URIs, going beyond the annotation baseline.

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

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

The description is front-loaded with the key preference directive and well-structured with examples and comparisons. However, it is somewhat long and could be trimmed without losing clarity, so it loses one point.

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

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

Despite lacking an output schema, the description thoroughly explains return value (structured answer with citations), provides extensive usage guidance, examples, and sibling comparisons, leaving no major gaps for a tool of this complexity.

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

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

Schema coverage is 100% with all parameters well-described as aliases for 'question'. The description adds little beyond the schema, simply restating that the parameter accepts natural language questions, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool routes factual questions to authoritative structured data, with specific verbs like 'ask' and resource 'Pipeworx'. It distinguishes from siblings by explicitly stating 'PREFER OVER WEB SEARCH' and listing alternatives like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit when-to-use guidance (factual questions, real-world entities) and when-not-to-use (hallucination-resistant or broad multi-part questions) with named alternative tools. Includes concrete examples of query types and phrasings like 'what is', 'look up', 'find'.

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 behavioral context: costs an extra LLM call, returns explicit refusal reasons, and extracts answer only from tool result, enhancing transparency beyond annotations.

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

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

The description is fairly concise and well-structured, front-loading key purpose and trade-offs. Each sentence adds value, though it could be slightly tighter without losing clarity.

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

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

Given the complexity (6 parameters, 1 required, full schema coverage, rich annotations), the description covers all necessary context. It explains the output format and refusal reasons, 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 each parameter described. The description lists aliases for the question parameter but adds minimal semantic meaning beyond what the schema already 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 defines the tool as a hallucination-resistant answer mode for high-stakes reads, explaining the extraction process. It distinguishes from the sibling ask_pipeworx by noting the extra LLM call and the context where it should be used.

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 when-to-use guidance is given: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with specific examples. It also advises preferring ask_pipeworx for casual lookups, providing clear alternatives.

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

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

The description extensively discloses behaviors beyond annotations: it resolves markets, classifies bets, fans out to category-specific data packs, returns structured results, handles low-confidence matches, dead markets, wide spreads, and resolution-rule risks. Annotations already indicate read-only and idempotent, but the description adds rich behavioral context without contradiction.

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

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

The description is extremely verbose, with many detailed fan-out examples and edge cases. While each sentence adds value, it could be more concise without losing critical information. The structure front-loads the main purpose but then dives into extensive specifics, making it lengthy.

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 lack of output schema, the description fully explains return values: market fields, analysis, evidence, resolver contract, parent event, news fields, safety mechanisms, and resolution rules. It covers all edge cases an agent needs to correctly 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%, but the description adds significant context for each parameter. For 'market', it explains formats. For 'depth', it defines 'quick' and 'thorough' with fan-out examples. For 'include_raw', it explains size implications. This adds meaning beyond the schema descriptions.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies input formats (slug, URL, question text) and outputs (evidence packet + comparison). The verb 'Research' and resource 'Polymarket bet' are explicit, differentiating it from siblings like polymarket_edges or polymarket_arbitrage.

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

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

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' While it does not explicitly mention when not to use, the context of sibling tools and the specific use cases provide clear guidance. The description could more directly exclude alternatives, but it is sufficient.

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

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

Annotations indicate read-only, idempotent, open-world behavior. The description adds significant behavioral details: it pulls latest financials from SEC EDGAR/XBRL, handles off-calendar fiscal years, sorts results, returns citation URIs. 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 trigger phrases and a clear statement, but it is somewhat lengthy. However, every sentence earns its place by adding value. Minor verbosity prevents a perfect score.

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 what is returned (paired data, citation URIs) and covers the complexity of two entity types, data sources, sorting, and replacement of many lookups. It is complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: for 'values' it provides concrete examples (tickers, drug names) and explains the max/min items; for 'type' it details what data each entity type retrieves. This helps the agent select appropriate parameters.

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

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

The description starts with clear trigger phrases like 'Compare X and Y' and explicitly states it does side-by-side comparison of 2-5 companies or drugs in one parallel call. It distinguishes itself from sequential lookups and specifies the data pulled for each entity type, making the purpose unambiguous.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear guidance on when to use this tool vs alternatives. It also gives examples of input phrases and explains the benefit of replacing many lookups.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds critical behavioral details: parallel facet routing, return format (findings packet with evidence, confidence, citation, gaps[]), expected latency (15-60s), and that it never invents answers. No contradiction with annotations.

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

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

The description is long but well-structured: front-loaded with account requirement and alternative tool, then functionality, output format, and use cases. Every sentence provides necessary context, though slightly verbose. Could be tightened without losing 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?

Given the tool's complexity (many siblings, no output schema), the description covers all key aspects: prerequisites, when to use alternatives, parallel behavior, return format, limitations (empty gaps for unstructured topics), and expected timing. No output schema exists, but the description sufficiently explains what the agent receives.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'depth' enum values (quick=3 facets, standard=5, thorough=8) and clarifying that 'question' should be natural language and can be broad/multi-part. This extra context justifies a 4.

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

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

The description clearly identifies a specific verb-resource pair: 'grounded multi-source research' across Pipeworx's structured data sources, not open-web search. It distinguishes itself from siblings like ask_pipeworx by stating it decomposes questions into facets and runs parallel tool invocations, whereas ask_pipeworx is a single LLM call.

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 (broad/multi-part questions over structured data), when not to use (breaking news, current news topics), and directly names the alternative (ask_pipeworx). Also notes account requirements and depth plan limitations, providing complete 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, destructiveHint. Description adds return details (top-N, names, descriptions, schemas, ready-to-call) beyond annotations.

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

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

Single paragraph with front-loaded purpose, concise yet informative. No wasted words, but could be structured with bullets for clarity.

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

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

Covers purpose, input, output, usage guidance. Lacks error cases or edge behavior, but sufficient for a discovery tool with no output schema.

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

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

Schema coverage is 100% with descriptions for all parameters. Description doesn't add new semantic meaning beyond schema; examples are in schema but not in description body.

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 finds tools by describing data/task, lists example domains, and distinguishes itself from sibling tools by positioning as a first-call for exploration.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover' and 'Call this FIRST when you have many tools.' Lacks explicit when-not-to-use but context is clear.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context: it fans out across multiple sources in one parallel call, mentions that patent source may sunset in May 2025 and 'soft-fails until reactivated', and details the data returned. This adds value beyond annotations without contradiction.

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

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

The description is front-loaded with example queries, then lists return components. While relatively long (multiple sentences), each sentence adds value given the tool's complexity. No wasted words, but could be slightly more structured (e.g., bullet points).

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

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

For a tool with no output schema, the description thoroughly explains return fields, sources, and constraints (e.g., up to 5 filings, patent soft-fail). It lacks pagination details but covers all key aspects of the tool's behavior. Adequate for its complexity.

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

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

Schema coverage is 100% with both parameters documented. The description adds additional context beyond schema: it specifies that value must be ticker or zero-padded CIK, provides examples ('AAPL', '0000320193'), and explains that names are not supported. This adds meaningful guidance despite high schema coverage.

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

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

The description explicitly states the tool provides a 'full cross-source profile of a US public company' in one parallel call, lists specific return fields (filings, fundamentals, patents, news, LEI), and differentiates it from sibling tools like 'resolve_entity' by stating 'names not supported — use resolve_entity first'. Verb+resource combination is clear and specific.

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

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

The description explicitly advises 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and clearly states when not to use: if only having a name, use resolve_entity. It also mentions that names are not supported, providing a clear alternative tool.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true, describing the core behavioral traits. The description adds no further details about behavior (e.g., error handling for non-existent keys, effects on related data), so it adds marginal value beyond the annotations.

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

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

Two sentences with no wasted words. The action is front-loaded, and all information is essential. Efficient and clear.

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

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

Given the tool's simplicity (1 parameter, no output schema, no nested objects), the description covers purpose, usage guidelines, and relationships with siblings. Combined with annotations, it provides a complete picture for an AI agent.

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

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

The input schema provides full coverage (100%) with a clear description for the single parameter 'key'. The description does not add additional semantic meaning beyond the schema, so a baseline of 3 is appropriate.

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

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

The description uses the specific verb 'Delete' and identifies the resource as 'previously stored memory by key'. It distinguishes from sibling tools by mentioning pairing with 'remember' and 'recall', making the tool's role 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?

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also advises pairing with 'remember' and 'recall', providing clear usage context and 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 (readOnlyHint, idempotentHint, destructiveHint false) indicate safe, non-destructive read operation. Description adds that it fetches the page, extracts title/description/key links, and emits standard markdown format, providing valuable behavioral context beyond annotations.

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

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

The description is a single well-structured paragraph covering purpose, process, output, and use cases. It is concise but not too terse, earning a 4.

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 two parameters with full schema coverage, no output schema, and clear description of output format, the description is complete enough for the tool's simplicity. It explains what happens and what the output looks like.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add additional meaning for the parameters beyond what the schema already provides (e.g., no further details on URL format or max_links behavior).

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 generates an llms.txt file for any URL, specifying verb and resource. It distinguishes from sibling tools like scan_competitor_ai_presence and ai_visibility_check, which serve different purposes.

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 use cases: indexing client sites, drafting for own projects, auditing competitors. However, it does not mention when not to use or alternative tools, which would elevate the score.

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, and openWorldHint. The description adds algorithmic detail (mod-10) and input format expectations, which are consistent with annotations and provide useful behavioral context beyond the flags.

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 extremely concise with two short sentences: first defines the function, second gives the use case. No extraneous 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 computation tool with one parameter and no output schema, the description is mostly complete. However, it does not specify the return format (e.g., single digit string), which would help an agent anticipate the output. Still, the purpose is clear and the description is sufficient for typical 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% and already includes parameter description and example. The description adds minimal value by naming the barcode standards (GTIN/EAN/UPC), but this is not essential 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 clearly states the tool computes the mod-10 check digit for GTIN/EAN/UPC data digits. It distinguishes from sibling 'validate_gtin' which validates full barcodes rather than generating check digits.

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

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

Description provides explicit use case 'generate or repair a barcode' but does not explicitly exclude alternatives such as validation. However, sibling tool 'validate_gtin' is available for validation, and the context makes the distinction 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, idempotentHint, destructiveHint. Description adds no additional behavioral context beyond the return fields, which is useful but not required given annotation coverage.

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

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

Two sentences, front-loaded with purpose, no wasted words. Efficiently conveys essential information.

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

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

Lists return fields, annotations cover safety and idempotency. Lacks mention of pagination or ordering, which is minor for a simple subscription list. Mostly 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?

Only one parameter with full schema description coverage. The description does not add extra meaning beyond what the schema provides, achieving 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?

Clearly states it lists the caller's active subscriptions and specifies the returned fields (id, type, params, etc.). Differentiates from siblings like subscribe and unsubscribe.

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

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

Provides explicit use cases: review before adding subscriptions or to find an id to cancel. Does not mention alternatives or when not to use, but context is clear enough.

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

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

The description discloses rate limits (5 per identifier per day), quota impact (free, doesn't count against tool-call quota), and that the team reads digests daily. Annotations provide no behavioral info, so description carries full burden and does so excellently.

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

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

The description is concise, front-loaded with purpose, then usage tips, then rate/quote details. Every sentence provides essential information without redundancy.

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

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

For a simple feedback tool, the description covers all necessary aspects: purpose, when to use, input specifics, rate limits, and quota impact. No output schema is needed, 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 the description adds value by explaining the enum values in context and giving guidance on message phrasing (e.g., be specific about tool/error). One nested object's fields are only covered by schema, not description, which is acceptable but could be improved.

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 is for sending feedback to the Pipeworx team, specifically about bugs, missing features, data gaps, or praise. It uniquely serves a feedback purpose not covered by any sibling 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 specifies when to use each feedback type (bug, feature, data_gap, praise) and advises against pasting end-user prompts, providing clear usage context.

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

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

Annotations already signal readOnly, openWorld, idempotent, non-destructive. The description adds caching behavior (5min–1h), data source (CF analytics-engine), no PII, and output structure (pack, tool, count). 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, no wasted words. Main purpose is front-loaded, followed by bullet-style use cases and a concise technical note. Every sentence earns its place.

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

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

No output schema, but the description explains return content (top tools, packs, total call volume), caching, and data source. Enough for an agent to understand what to expect. The sibling list is large but the description uniquely positions this tool as a trending aggregate.

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 one optional enum parameter. The description adds practical guidance beyond schema: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps agents choose the right window.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a configurable window, using specific verbs and resources. It distinguishes itself from siblings by focusing on aggregated trending usage data, not individual queries or entity discovery.

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

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

Three explicit use cases are listed (discovering hot data sources, confirming canonical tools, aligning use case). Window options are compared: shorter for hot right now, longer for steady-state. No explicit when-not or alternatives among siblings, but the context is sufficiently clear for an agent to decide.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description details the detection logic, similarity threshold, partition filter, and fill check. It discloses behavioral traits like the requirement for at least one argument and how results are computed, with no contradiction to annotations.

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

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

The description is detailed but information-dense. It is front-loaded with the required constraint. While a bit lengthy, every sentence adds value, and structuring with bullet points could improve readability slightly.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly explains the response structure, error conditions, and related tools. It covers edge cases like placeholder slugs and fill checks, making it fully complete for an agent.

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

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

The input schema has 100% coverage with descriptions for both parameters, and the description adds significant value by explaining the modes, accepted formats (slugs or URLs), and consequences of each choice, making the meaning clear 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 that the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes between single-event mode (event) and cross-event mode (topic), and differentiates itself from sibling tools 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?

The description explicitly states that one of event or topic is required, recommends event for specific markets and topic for cross-event scanning, and directs to polymarket_fill_risk for custom sizing. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false; the description adds rich behavioral context beyond these, such as caching at 1h keyed on knobs, tradeable-edge filters (min_liquidity, max_spread_pp), diagnostics to show why segments are empty, and edge calculations with slippage. 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 very detailed and lengthy, containing several paragraphs with technical specifics. While well-structured with headers and lists, it could be more concise for an AI agent. It retains necessary detail but sacrifices brevity.

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 (9 parameters, no output schema), the description is thorough: it explains the three response segments, diagnostics, edge formulas, fed bets, caching, and all knobs. It covers what the output contains (by_segment, fed_candidates, _diagnostics), fully compensating for the lack of output schema.

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

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

Schema coverage is 100% with descriptions for all 9 parameters, providing a strong baseline. The description adds extra context like 'Polymarket has zero trading fees as of 2024' and 'Partition arbs always return kelly_fraction_half=0', which enhances understanding beyond the schema but is not critical.

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

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

The description clearly states the tool 'scans top Polymarket markets' and returns opportunities where Pipeworx data disagrees with market price. It specifies the verb 'scan' and resource 'top Polymarket markets', distinguishing it from siblings like polymarket_arbitrage and bet_research by focusing on Pipeworx data versus market price.

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

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

The description explicitly mentions it is 'built for what should I bet on today' and helps agents discover opportunities without paging hundreds of markets. However, it does not provide explicit when-not-to-use guidance or contrast with alternative sibling tools like polymarket_arbitrage, though the context is clear.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds significant context: it reads snapshots, computes trends, returns time-series, explains expired opportunities, and details limits and computation. 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 packed with information but well-structured with caps for response fields. Every sentence adds value, though slightly long; could be more concise but maintains clarity.

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

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

No output schema, so description must cover return values. It fully explains tracked[], expired[], snapshot_dates[], along with fields and limits. Complete for an AI agent to understand and use 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?

Schema has 100% coverage for both parameters. The description adds meaning: days lookback with default/max, window with family options. Slight inconsistency in max (description says 30, schema clamp 2-30) but still 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?

The description clearly states the tool provides edge persistence and decay telemetry from daily polymarket_edges snapshots, answering specific questions about how long an edge has existed. It distinguishes from the sibling polymarket_edges by focusing on persistence vs. single snapshot 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 explains what the tool answers and includes limits (60-day TTL, snapshot start, decay computation). It lacks explicit 'when not to use' or alternatives, but the context and thoroughness allow the agent to infer appropriate usage.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint. Description adds that it walks the order book ladder, returns top-of-book, VWAP, slippage, verdict, and warns about thin books and partial fills. 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 well-structured with sections and front-loaded with purpose. However, it is somewhat verbose, with phrases like 'the dominant loss mode in real arb-bot P&L' that add color but could be trimmed.

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

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

Despite no output schema, the description thoroughly explains all return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, per-leg detail, thin_legs, forced_directional_risk). It covers both modes and provides adequate context for an agent to invoke correctly.

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

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

Schema description coverage is 100%. Description adds meaning by explaining the behavior of side and size in each mode (single-market vs basket), defaults, and interpretation of basket notional. This goes 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 performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It also provides context on when to use it relative to sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why, giving clear conditions for use and warning against partial fills.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds rich behavioral context: safety fields, temporal alignment, skipped leg comparisons, and the caveat that most topic shortcuts currently return warnings. 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?

Description is detailed and structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). While slightly long, every sentence adds necessary information for correct usage. Could be slightly more concise, but appropriateness weighs high.

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

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

Despite no output schema, the description fully explains response fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and edge cases. Covers all aspects needed for an agent to interpret results 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%, but description adds value by explaining the two modes and how parameters interact (topic auto-fetches, explicit overrides). Provides concrete examples and clarifies the list of valid topic values.

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

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

The description explicitly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes from sibling tools by focusing on cross-venue comparison, not single-venue arbitrage or edge detection.

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 detailed guidance on when to use: two modes (topic shortcuts vs explicit tokens), explains safety fields and when spreads are meaningful or not (compatibility_warning, temporal_alignment). Implicitly tells when not to use when safety warnings fire.

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 behavioral detail: what happens when key is omitted (lists all keys), and scoping by identifier. 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?

Three sentences, front-loaded with core function, no fluff. Each sentence adds value: function, usage, scoping/pairing.

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

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

For a tool with one optional parameter and no output schema, the description is fully complete: explains functionality, when to use, behavior, and integration with sibling tools.

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

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

Schema coverage is 100% with clear description. The tool description restates the parameter behavior but does not add significant new meaning beyond the schema.

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

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

The description clearly states the tool retrieves stored values or lists keys, with specific examples (ticker, address, notes). It distinguishes from siblings 'remember' and 'forget' by naming them in context.

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

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

Explicitly says when to use (look up context), provides examples, and mentions scoping. Does not explicitly state when not to use, but the context is clear enough.

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

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

The description states that setting mark_read:true flags events as read (a state change), but annotations declare readOnlyHint=true, indicating no state modification. This contradiction undermines transparency. The description adds useful behavioral detail (e.g., polling suitability, return structure) but the contradiction outweighs these benefits.

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. It efficiently covers filters, return data, a behavioral flag, and an alternative access method. No redundant or irrelevant information is present.

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

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

Given no output schema, the description adequately explains return structure (source, citation_uri, raw payload). It covers filtering, the mark_read side effect, and polling suitability. However, it lacks details on ordering, error conditions, and edge cases for limit and unread_only, which are partially covered by schema descriptions.

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

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

The description enhances the schema by providing examples (e.g., 'sec_8k' for type), explaining the effect of mark_read (advancing read pointer), and noting polling suitability. With 100% schema coverage, baseline is 3, but the additional context 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 states the tool pulls fired events from a subscription feed, specifying the returned data (source, citation_uri, raw payload) and available filters. It distinguishes itself by mentioning the same feed available via an HTTP endpoint, though not explicitly compared to sibling tools. The verb+resource combination is specific and 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 context on when to use the tool (e.g., polling, filtering by type and since) but does not compare against sibling tools like list_subscriptions or recent_changes. The mention of an alternative HTTP endpoint offers some guidance, but no clear when-not-to-use or explicit alternatives among MCP 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 cover safety (readOnlyHint, idempotentHint). The description adds details: fan-out to multiple sources, fallback from GDELT to GNews, soft-fail for USPTO, and return structure with grouped changes and citation URIs, going beyond annotations.

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

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

The description is somewhat verbose but front-loads query examples and efficiently conveys multi-source behavior and alternatives. It could be trimmed slightly but remains clear and comprehensive.

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

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

No output schema exists, but the description explains the return structure (changes[] grouped by source, total_changes count, citation URIs). It covers all essential aspects for an agent to understand and use the tool correctly.

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

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

Schema has 100% description coverage. The description adds examples of relative time shorthands ('7d', '30d', '3m', '1y'), typical usage ('Use "30d" or "1m"'), and explains that value accepts ticker or CIK, enriching schema information.

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

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

The description clearly states the tool provides a change feed for a company over a time window, listing specific sources (SEC EDGAR, GDELT→GNews, USPTO) and result structure. It distinguishes from sibling 'entity_profile' by noting that one provides static profile instead.

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 query examples like 'What's new with X' and 'latest on Y' are provided. The description also gives a clear alternative: 'Use entity_profile instead when you want the static profile', guiding selection between tools.

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

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

Beyond annotations, the description adds persistence details: scoped by identifier, authenticated users get persistent memory, anonymous sessions retain memory for 24 hours. 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 concise with four sentences, front-loaded with purpose, then usage, then pairing, then persistence. Every sentence adds value.

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

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

Given the simple key-value nature, no output schema, and good annotations, the description covers all necessary aspects: purpose, usage, behavior, parameters, and pairing with siblings.

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 largely repeats the examples from the schema for both key and value. It adds no significant new meaning beyond what the schema already 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 that the tool saves data for reuse across conversations or sessions, with specific verb 'Save' and resource 'data'. It distinguishes itself from sibling tools 'recall' and 'forget' by explicitly mentioning pairing.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward... so you don't have to look it up again'. Also provides clear alternatives: 'Pair with recall to retrieve later, forget to delete.'

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, openWorldHint, idempotentHint, and no destructiveness. The description adds that each call cascades through multiple lookup endpoints internally, replacing 2-3 manual lookups, and mentions citation URIs returned.

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 few well-structured sentences, starting with example queries, then primary use case, then type-specific 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 fully describes return formats for each type, including citation URIs. It is complete for a resolution tool with clear inputs and outputs.

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 provides 100% coverage with descriptions, but the description adds significant detail: for 'type' it explains the specific outputs per type, and for 'value' it gives example formats. This goes beyond the schema.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, gives example queries, and lists supported types (company, drug) with specific outputs. It distinguishes from siblings by noting other tools require the identifier 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?

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It implies when not to use, but does not explicitly mention alternatives or exclusions.

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, openWorld, non-destructive. The description adds valuable behavioral context: it calls ai_visibility_check under the hood, ranks results, and returns specific metrics (score, confidence, signal density). 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 concise: two sentences plus a brief use-case note. Front-loaded with the core action ('Compare AI visibility...'). Every sentence is informative with no wasted words.

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

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

Given the tool's complexity (multi-entity comparison, no output schema), the description covers all necessary aspects: purpose, process (probes with ai_visibility_check), output (ranked list with metrics), and parameter constraints. No gaps in information.

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

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

Schema coverage is 100% with descriptions. The description adds meaning beyond schema: entities must be 2-8 with first as subject, models and _apiKey conditional usage, context for disambiguation. This enhances understanding of parameter semantics.

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

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

The description clearly states the tool compares AI visibility across multiple entities, rank them, and surfaces which is most/least recognized. It explicitly distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by mentioning it probes each entity with ai_visibility_check and returns a ranked list.

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

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

The description provides a clear use case: competitive AI-marketing audits to compare how well different entities are known by AI. It implies when to use this tool vs. alternatives (e.g., for single entity use ai_visibility_check), but does not explicitly state when not to use it or list alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds substantial behavioral context: partial failures, possible 5-30s delay on first bundlephobia measurement, and specifics about return fields (summary, advisories, alternatives). 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?

Description is front-loaded with the core purpose but is slightly verbose due to detailed listing of return fields and error handling. Every sentence is valuable, but could be tightened slightly. Still, it is well-structured and 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?

Despite no output schema, the description covers all necessary context: data sources, return fields (explicitly listed), version handling, error behavior, ecosystem limitations, and graceful degradation. 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 coverage is 100% with clear descriptions for both 'package' and 'version'. Description adds extra meaning: confirms scoped packages (e.g., @types/node) are accepted and states version defaults to latest, which enhances understanding beyond schema.

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

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

The description clearly states the tool's purpose: a composite check for whether to add an npm package, combining deps.dev and bundlephobia data. It is a specific verb+resource+scope and is easily distinguished from sibling tools like bet_research or validate_claim.

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 (e.g., 'is X safe/popular/small') and provides exclusions (NPM only, other ecosystems fall under deps.dev:version directly). Also explains graceful degradation during latency, giving clear usage 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, openWorldHint, idempotentHint, and destructiveHint. The description adds detailed behavioral traits: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flagging, and returns character offsets and similarity scores.

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

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

The description is appropriately sized and front-loaded: first sentence states purpose, then usage guidelines, then technical details. Every sentence adds value with zero 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?

Despite no output schema, the description explains what is returned (top-N passages with character offsets and similarity scores). It also covers pairing with another tool, making it complete for a tool of this complexity.

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

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

Schema coverage is 100%. The description adds value beyond schema by explaining the max char limit for 'text', the natural-language role of 'query', and the default for 'limit'. This helps an agent understand the parameters' semantics.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifying the verb 'search', the resource 'text', and the scope 'within a record'. It distinguishes itself by noting it's for records too large for the prompt.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' Provides an alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages.'

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

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

The description goes beyond annotations by detailing authentication requirements, delivery channel behaviors (auto-disable after 10 failures), and rate limits. It does not explicitly address idempotency (annotations set idempotentHint=true), but the description implies that each call creates a new subscription with a new ID, which could be a contradiction. However, the overall behavioral disclosure is rich.

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: it opens with the core action and return value, then details types and delivery options. Each sentence adds necessary information without redundancy. It is appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (multiple subscription types, nested params, delivery options), the description covers all essential aspects: prerequisites, supported types, parameter format, delivery behaviors, and return value (subscription id). No gaps remain for an AI 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?

With 100% schema coverage, the description adds substantial value by providing detailed examples for each subscription type (e.g., 'sec_8k: {ticker:"AAPL", items?:["5.02","1.01"]}') and explaining delivery channel options with constraints. This greatly enhances understanding beyond the raw schema.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses a specific verb ('Create') and resource ('subscription'), and the scope is unambiguous. It effectively distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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, including prerequisites ('Requires a Pipeworx OAuth account') and delivery channel limitations (e.g., '10/day cap' for SMS). It does not explicitly state when not to use it or list alternative tools, but the context is sufficient for an AI agent to decide. A slight improvement would be mentioning sibling tools for viewing or removing subscriptions.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds context about what the tool returns (category-bucketed example questions with exact tool+argument shapes) and that it draws from a live catalog of thousands of tools. No contradictions. Only minor gap: doesn't discuss any potential rate limiting or size of output.

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

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

The description is thorough but reasonably concise for an onboarding tool. It front-loads example questions, then explains output structure and usage. Every sentence adds value, though it could be slightly more streamlined.

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 tool is complex as an entry point with no output schema. The description fully explains what to expect: categories of questions, how each answer comes with exact tool shapes, and how to use parameters. Adequate for an agent to understand and invoke correctly.

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

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

Schema coverage is 100% with one optional parameter. Description adds meaning: explains default behavior (full spread without arguments) and lists valid topic values (finance, pharma, etc.) with examples. This goes beyond the schema's description.

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

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

The description clearly defines the tool as an onboarding entry point that returns category-bucketed example questions. It uses specific verbs ('returns') and resource ('example questions') and distinguishes it from sibling tools like discover_tools by focusing on suggesting questions rather than listing all tools.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' Also provides alternative usage with the `topic` parameter to focus on specific areas. No exclusion needed; the description gives clear context for use.

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

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

Discloses that the row is deactivated not deleted, and historical events remain, adding context beyond annotations which only indicate idempotent and non-destructive.

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, efficient and front-loaded with primary action. No wasted words.

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

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

For a tool with 1 parameter, no output schema, and clear annotations, the description fully explains behavior and side effects.

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?

Single parameter 'id' is fully described in schema; description adds no additional semantic value beyond what 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?

Describes specific action 'Cancel a subscription by id', distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Clearly states ownership enforcement, implying when not to use (cannot cancel others' subscriptions). Contextual guidelines are present but no explicit alternative named.

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, idempotentHint, etc. The description adds behavioral context by stating it replaces 4-6 sequential calls and details the return format (verdict, structured form, citation, delta), which is valuable beyond the annotations.

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

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

The description is a single, well-structured paragraph that front-loads trigger phrases and clearly explains purpose, scope, and return value. It is concise without being terse, containing necessary information without 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 single-parameter tool without output schema, the description provides detailed information about the return value (verdict types, structured form, citation, delta) and the domain (company-financial claims). This is fairly complete, covering what the tool does and what it produces.

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 the 'claim' parameter well-defined in the schema. The description adds example claims and context, which is helpful but not essential given the schema already describes the parameter adequately. Baseline 3 is appropriate.

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

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

The description explicitly states the tool verifies natural-language claims against authoritative sources, focusing on company-financial claims for public US companies. It includes trigger phrases and clearly distinguishes from sibling tools like compare_entities or deep_research.

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

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

The description advises to use this tool whenever the agent needs to check factual correctness of a user's statement, which is clear guidance. It also specifies the scope (company-financial claims) but does not explicitly mention when not to use it, though the scope implies exclusions.

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 value by noting spaces/dashes are ignored and that it validates the number, not the product. 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 concise with three sentences, front-loaded with the main purpose. Every sentence adds necessary 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?

The tool has no output schema, so the description should explain return values. It partially does (check digit, format, GTIN-14, prefix/country) but does not list exact output fields. Adequate but not thorough for a validation tool.

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

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

Schema coverage is 100%, so the schema fully documents the single parameter. The description adds example values but no additional semantic meaning beyond what the schema provides. Baseline score 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 clearly states the tool validates barcode numbers, lists supported formats (EAN-13, UPC-A, EAN-8, GTIN-14), and details what it does (check digit, format, normalization, prefix/country). It distinguishes from sibling 'gtin_check_digit' by being more comprehensive.

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 lacks explicit guidance on when to use this tool versus alternatives like 'gtin_check_digit'. It only mentions it validates the number, not the product, but does not provide context for tool selection.

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