Scryfall

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows it's a safe read operation. The description adds behavioral context: it specifies that Anthropic calls require the user's own API key and incur costs, and describes the return structure per model. This adds value beyond the 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 well-structured and front-loaded: it starts with the action verb 'Probe', then covers default behavior, optional key usage, return format, and use cases. Every sentence adds value, and the overall length is appropriate for the tool's moderate complexity. A slight reduction in wordiness would earn a 5.

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

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

Given the tool has no output schema, the description adequately explains the return value structure (per-model object with fields) and lists relevant use cases. It covers the key aspects an agent needs to understand the tool's behavior and results, though it could mention how scores are computed or what 'signals' specifically refer to.

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's param explanations are helpful but not essential. The description reinforces schema details (e.g., 'workers-ai' default, 'anthropic' requires _apiKey) but does not add new semantic meaning beyond what the schema already provides. Baseline of 3 is appropriate.

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

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

The description clearly states the tool probes LLMs for knowledge and scores visibility (0-100) per model. It specifies the default model and optional Anthropic integration, and lists concrete use cases like 'AI-marketing audits, pre-launch brand checks, competitive monitoring', which differentiates it from siblings like scan_competitor_ai_presence by focusing on scoring rather than mere presence.

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

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

The description provides clear context on when to use the tool (brand audits, pre-launch checks, competitive monitoring) and explains key usage details like the default model and BYOK for Anthropic. However, it does not explicitly state when not to use it or mention alternatives, so it lacks exclusion 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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: routes to the right tool among 3,401, fills arguments, returns structured answers with pipeworx:// citation URIs. This goes 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 long but front-loaded with the key instruction 'PREFER OVER WEB SEARCH'. Every sentence adds value, providing examples and context. Could be slightly shorter but remains effective.

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

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

Given the tool's complexity (works with 3,401 tools across 767 sources) and no output schema, the description is remarkably complete. It explains behavior, routing, return format (structured answer with citation URIs), and provides numerous examples. Nothing essential is missing.

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

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

Schema coverage is 100% with a single parameter 'question' clearly described. The description adds aliases and examples but does not significantly expand on the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: answering factual questions using structured data from many authoritative sources. It specifies domains like SEC filings, FDA data, etc., and distinguishes itself by saying 'PREFER OVER WEB SEARCH'. The verb 'ask' and resource 'pipeworx' are specific.

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

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

The description provides explicit when-to-use guidance, including specific question types and examples (e.g., 'current US unemployment rate'). It implies preferring over web search but does not explicitly state when not to use (e.g., subjective or open-ended questions). Still, the guidance is clear and context-rich.

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?

Extremely detailed: describes resolution, classification, parallel fan-out, response shapes, resolver contract, parent event extractor, news fields, safety mechanisms (low-confidence, closed markets, wide spread). Annotations confirm read-only and idempotent. No contradictions.

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

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

The description is thorough but verbose, containing many details that could be organized or condensed. The first sentence effectively front-loads the purpose, but overall length and density reduce conciseness.

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

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

Despite no output schema, the description fully explains output fields (market, analysis, evidence) and covers edge cases (low-confidence resolution, closed markets, illiquid spreads). Complex tool with complete documentation.

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

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

Schema coverage is 100% with descriptions for all three parameters. The tool's description adds context for the market parameter (examples) but mostly repeats schema info. Baseline 3 is appropriate.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, specifying input types (slug, URL, question text) and outputs (evidence packet, comparison). It distinguishes from sibling tools by focusing on a single bet research, while siblings like polymarket_edges target specific angles.

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 like 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Does not explicitly state when not to use it or suggest alternatives, 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?

Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds valuable context: the tool makes a single parallel call, handles off-calendar fiscal years correctly, returns sorted results by primary metric, and outputs paired data with citation URIs. This goes beyond annotations, justifying a 4.

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-organized with trigger phrases, a clear preference statement, separate handling for each type, and a note about output format. Every sentence adds value, but the justification 'Replaces 8–15 sequential lookups' is slightly redundant given the earlier preference statement. Otherwise efficient and front-loaded with key information.

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

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

Given the tool has no output schema, the description comprehensively explains returns: paired data with citation URIs per entity, sorted by primary metric. It covers both entity types, mentions edge cases like off-calendar fiscal years, and quantifies efficiency gains. This is fully adequate for an AI agent to understand and invoke the tool correctly.

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

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

The input schema already has 100% description coverage with basic explanations. The description adds significant meaning: for type='company', it specifies 'LATEST 10-K revenue + net income + cash + long-term debt from SEC EDGAR/XBRL'; for type='drug', it specifies 'FAERS adverse-event counts, FDA approval counts, active trial counts'. It also clarifies the format of values (tickers/CIKs vs drug names) and mentions max/min items. This exceeds the schema baseline.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs in a single parallel call. It specifies exact metrics for each type (e.g., 10-K financials for companies, FAERS data for drugs) and distinguishes from siblings like entity_profile by explicitly recommending this tool over sequential single-pack lookups.

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

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

The description provides explicit triggers (e.g., 'Compare X and Y', 'which is bigger') and a strong preference statement ('ALWAYS PREFER over sequential single-pack lookups'). It does not explicitly state when not to use this tool, but the context makes the usage clear. A score of 4 reflects the clear context without exhaustive 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=true and idempotentHint=true. The description adds useful behavioral context: returns top-N relevant tools with full schemas and curated examples, no second lookup needed. 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 somewhat long (4 sentences) but front-loaded with the key purpose and usage. Every sentence adds value, but could be slightly more concise. Structure is 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?

No output schema is provided, but the description explains what is returned: tool names, descriptions, full input schemas with examples. It also mentions the default/max limit. Adequate for a discovery tool with good annotations.

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

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

Schema coverage is 100% with descriptions for each parameter. The description mentions aliases (task, q, search, description) but does not add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool finds tools by describing data or task, with specific verb 'Find tools' and resource 'tools'. It distinguishes itself from siblings (e.g., search_cards, entity_profile) by being a discovery/search tool, not a specific data retrieval tool.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)'. It mentions when to use (browse/search/look up) but does not explicitly state when not to use or exclude alternatives, though context implies it's for exploration.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds substantial behavioral context: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), returns specific fields (cik, filings with URIs, fundamentals, patents, news, LEI), and notes that USPTO PatentsView API may sunset in May 2025 and will soft-fail. It also explains fallback mechanisms (GDELT→GNews). 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 relatively long but each sentence contributes useful information: query examples, preferred usage, data sources, return fields, limitations. It is front-loaded with examples and has a logical structure. While not extremely concise, the density of information justifies the length.

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

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

Without an output schema, the description thoroughly explains what the tool returns: cik, company_name, recent_filings (up to 5 with URIs), fundamentals (sorted), patents (with sunset note), recent news (with fallback), and LEI. It also covers input constraints and the tool's parallel execution. This provides complete context for an agent to understand the tool's capabilities and limitations.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by providing concrete examples ('AAPL' for ticker, '0000320193' for CIK), clarifying the zero-padding requirement, and explicitly stating that names are not supported. This goes beyond the schema's basic 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 defines the tool as creating a full cross-source profile of a US public company in one parallel call. It provides multiple example queries (e.g., 'Tell me about X', 'research Acme', 'brief me on Tesla') and explicitly contrasts with chaining separate SEC/XBRL/news lookups, making the purpose highly specific and distinguishable from siblings.

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

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

The description contains explicit usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies when not to use the tool (if only a name is given, use resolve_entity first) and lists supported inputs (ticker or zero-padded CIK, not names). This provides clear when-to-use and when-not-to-use instructions.

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

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

Annotations already mark destructiveHint=true and idempotentHint=true. The description adds 'Delete' confirming destructive behavior, but does not elaborate on side effects, reversibility, or error handling. The annotations carry the main burden, so description provides marginal added transparency.

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

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

The description is two sentences long, with the first sentence stating the core purpose and the second providing usage context and related tools. No redundant information, every sentence earns its place.

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

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

Given the simple tool (single parameter, no output schema, clear annotations), the description covers purpose, usage scenarios, and related tools. It is complete and sufficient for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100% and the parameter description in the schema ('Memory key to delete') is clear. The tool description does not add any additional meaning beyond what the schema already provides, meeting the baseline expectation.

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

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

The description clearly states the action 'Delete a previously stored memory by key', specifying the verb (delete) and resource (memory by key). It also distinguishes from sibling tools by mentioning pairing with 'remember' and 'recall'.

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

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

The description provides explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with 'remember' and 'recall', but does not explicitly state when not to use, leaving a minor gap.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds value by explaining the fetch-and-extract process and output format ('single text blob ready to drop at site-root/llms.txt'), providing 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 that front-loads the core purpose. It covers purpose, process, output, and use cases without redundancy, though it could be slightly more concise.

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

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

Given the tool's simplicity (2 params, no output schema, detailed annotations) and the description covering functionality, output, and use cases, it is complete enough for an agent to use correctly. It does not address errors or edge cases, but those are less critical for a read-only, idempotent tool.

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

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

The input schema has 100% coverage, with both 'url' and 'max_links' described. The description does not add extra meaning beyond the schema (e.g., example URL is already in param description). Baseline of 3 is appropriate when schema covers parameters well.

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

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

The description clearly states the tool generates an llms.txt file for a URL, using specific verbs like 'generate', 'fetch', 'extract', and 'emit'. It specifies the resource (llms.txt) and the target AI crawlers, effectively distinguishing its purpose from sibling tools.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitor. It gives clear context for when to use, though it doesn't explicitly mention when not to use or alternatives, which is acceptable given no similar sibling tool exists.

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

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

Annotations already declare readOnly, idempotent, openWorld. Description adds fuzzy matching behavior and details about returned fields, complementing 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?

Single, front-loaded sentence covering purpose, matching behavior, and return fields. No extraneous content.

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

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

Given tool simplicity (2 params, no output schema), description adequately covers purpose, input (fuzzy name, optional set), and output contents. No missing critical details.

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

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

Schema already provides full descriptions for both parameters (name, set). Description reaffirms fuzzy matching for name and optionality of set, adding minimal 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?

Clearly states it looks up a single MTG card by name with fuzzy matching, listing specific return fields (mana cost, oracle text, etc.). Differentiates from sibling tools like search_cards (multiple) and random_card.

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?

Implied usage for single card lookup but no explicit comparison to siblings or when-not to use. Missing guidance on when to choose this over search_cards or random_card.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds that it returns specific fields but no additional behavioral traits beyond what annotations provide.

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

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

Single sentence, front-loaded with verb and resource, 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?

With no parameters, good annotations, and no output schema, the description fully captures what the tool returns (codes, names, types, release dates, card counts).

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% (no parameters). Baseline 3 applies; description adds no parameter information, which is acceptable given no parameters exist.

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

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

The description uses a specific verb 'List' and identifies the resource 'all MTG sets/expansions', clearly distinguishing it from card-level tools like get_card or search_cards.

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

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

The description implies its usage for listing sets but does not explicitly state when to use or avoid this tool, nor does it mention alternatives among sibling 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?

The description discloses rate limiting (5 per identifier per day), that it is free and doesn't count against tool-call quota, and that feedback affects the roadmap. The annotations (readOnlyHint: false) align with the write nature of the tool, with no contradictions.

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

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

The description is concise (4-5 sentences) and front-loaded with the main purpose. Every sentence adds value: purpose, use cases, guidelines, rate limits, and pricing. No redundancy or unnecessary detail.

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 (no output schema, three parameters with full schema coverage), the description covers all necessary aspects: purpose, parameter behavior, rate limits, and usage guidance. It is complete for an agent to invoke correctly.

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

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

Although schema coverage is 100%, the description adds valuable context beyond the schema: it explains the enum values for 'type' in detail, advises on message specificity and length, and describes optional context fields. This helps the agent use parameters correctly.

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

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

The description clearly states the tool's purpose: providing feedback to the Pipeworx team about bugs, features, data gaps, or praise. It distinguishes itself from sibling tools like ask_pipeworx (Q&A) and remember (memory) by focusing on feedback.

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

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

The description explicitly lists when to use the tool (bug, feature/data_gap, praise) and provides best practices like describing issues in terms of tools/packs instead of pasting user prompts. It also mentions rate limits and that it doesn't count against quota.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds value by disclosing caching behavior (5min-1h), data derivation (CF analytics-engine), and absence of PII, which annotations do not cover.

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

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

Four sentences with a clear front-loaded purpose followed by bullet-style use cases. Every sentence provides necessary information without redundancy. Could be slightly tighter but is efficient overall.

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 single-parameter schema, rich annotations, and absence of an output schema, the description fully covers what the tool returns (top tools, packs, volume), caching, data source, and privacy. No gaps remain.

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

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

Schema coverage is 100% with a well-described enum. The description adds practical context for choosing window lengths ('Shorter windows surface what's hot right now; longer windows show steady-state demand'), going beyond the schema description.

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

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

The description clearly states the verb and resource: 'returns the top tools, top packs, and total call volume over a recent window'. It distinguishes from siblings by focusing on trending data aggregated from all AI agents, unlike discover_tools or ask_pipeworx.

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 three use cases (discovering hot data, confirming canonical tool, seeing alignment) and provides guidance on window selection (short vs long windows). However, it does not explicitly state when not to use it or suggest alternative tools.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior, but the description adds critical behavioral details: the semantic anchor (Jaccard similarity threshold 0.30), partition filter for placeholder slugs, and the exact conditions under which a null arb signal is returned. 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 with clear sections and front-loaded requirements. Every sentence adds value, though a minor trim could improve readability without losing information.

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

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

Despite the lack of an output schema, the description thoroughly explains the response structure, edge cases (low similarity, placeholder filtering), and the logic behind both modes. It provides all necessary context for an AI agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description enriches both parameters with usage context, examples, and accepted formats (e.g., full URLs accepted for event). This significantly adds meaning beyond the schema's property 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 defines the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between two modes (event and topic) with specific examples, so the agent understands the exact resource and operation.

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

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

The description explicitly states the requirement for either 'event' or 'topic' parameter and warns that calling with no args fails. It recommends event mode for specific markets and topic mode for cross-event scanning, but does not differentiate from sibling tools like polymarket_kalshi_spread or polymarket_edges.

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

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

The description provides extensive behavioral details: model families, edge calculations, caching (1h), and diagnostics. Annotations confirm read-only and idempotent, with no contradictions. The description adds significant value beyond annotations.

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

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

The description is well-structured with sections and clear sentences, but it is quite lengthy. It front-loads purpose effectively, but every sentence earns its place. Minor conciseness improvements could be made.

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 return structure (segments, diagnostics) and caveats (Fed bets). It covers the tool's complexity comprehensively, leaving no gaps for an agent.

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

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

Schema coverage is 100%, but the description adds meaning by explaining tradeable-edge knobs, filtering logic, and default behaviors. For example, min_partition_leg_kelly is clarified. This exceeds the baseline of 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's purpose: scanning Polymarket markets for opportunities where Pipeworx data disagrees with market price. It uses specific verbs and resources, and distinguishes from sibling tools like 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 it's built for 'what should I bet on today' and explains when to use it. However, it does not directly compare with alternative tools or state when not to use it, 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?

The description extensively explains behavioral details beyond annotations: safety fields like compatibility_warning, temporal_alignment, skipped_cross_type/subtype, and conditions where spreads are meaningless (aligned:false). This adds significant value over the annotations which only provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint.

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 dense with necessary information, front-loaded with purpose, then details modes, response, and safety fields. Every sentence contributes value; however, it could be slightly more concise or structured for easier scanning.

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

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

Given no output schema, the description thoroughly explains the response structure (leg-by-leg prices, spread array, safety fields) and covers all scenarios (matched_pairs=0 cases, temporal alignment). It provides complete context for using the tool effectively.

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

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

The input schema has 100% description coverage for all three parameters. The description adds meaning beyond the schema by explaining the two modes, how parameters interact (explicit overrides topic), and providing the list of valid topic values. This enhances understanding of parameter usage.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question, specifying two distinct modes (topic shortcuts and explicit event pairings). It distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description explicitly indicates when to use the tool (to find spreads between venues) and warns that most pre-mapped topics return compatibility warnings and are not tradeable, guiding appropriate use. It does not explicitly contrast with sibling tools but implies its unique function.

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 says 'random', implying non-deterministic results, but annotations include 'idempotentHint: true', which contradicts this. No further behavioral details are provided, and the contradiction confuses expected behavior.

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

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

A single, clear sentence front-loads the core purpose. No unnecessary words or repetition.

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

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

For a simple tool with one parameter and good annotations aside from the contradiction, the description is adequate. However, the idempotency contradiction undermines completeness, leaving ambiguity about behavior.

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

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

Schema coverage is 100% with a description for the single optional parameter. The description adds no extra meaning beyond the schema, such as format or constraints, but includes a usage example.

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 'Get a random Magic: The Gathering (MTG) card' with optional filtering. This distinguishes it from siblings like 'get_card' (specific card) and 'search_cards' (search), making its purpose unambiguous.

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

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

The description mentions optional filtering by query but does not provide explicit guidance on when to use this tool versus alternatives like 'get_card' or 'search_cards'. The context is clear but lacks exclusion criteria.

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

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

Annotations already indicate readOnly and idempotent behavior. Description adds value by explaining scoping to identifier (anonymous IP, key hash, account ID) and relationships to sibling tools. No contradictions with annotations.

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

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

Three sentences, each essential. Front-loaded with core purpose, followed by usage context and scoping. No wasted words; structure is efficient.

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

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

Tool has low complexity with one optional parameter. Description covers retrieval, listing, scoping, and tool relationships. Without an output schema, it adequately describes expected behavior.

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

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

Schema coverage is 100% with parameter 'key' described in-schema. Tool description repeats 'omit to list all keys' but adds no new semantic meaning beyond schema examples. Baseline 3 is appropriate given high coverage.

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

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

Description clearly states the tool retrieves saved values or lists keys. It distinguishes itself from siblings 'remember' (save) and 'forget' (delete) by explicitly naming them. Verb 'retrieve' and resource 'value previously saved via remember' are specific.

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

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

Description provides context on when to use: looking up stored context without re-deriving. It mentions omitting key to list all and pairs with remember/forget. While it doesn't explicitly state when not to use, the context is sufficient for a simple retrieval tool.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds significant behavioral context: it fans out to multiple data sources, explains fallback order (GDELT preferred, GNews on error), notes USPTO sunset soft-fail, and describes the return structure (grouped by source, total_changes count, citation URIs).

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 examples at the start, followed by source details, parameter explanations, return format, and alternative tool. It is slightly dense but efficiently packs necessary information without unnecessary words.

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

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

Despite lacking an output schema, the description fully explains what the tool returns (changes grouped by source, total_changes count, pipeworx citation URIs). It covers all inputs, sources, edge cases (USPTO soft-fail), and provides guidance on when to use an alternative tool. For a 3-parameter tool with multiple sources, this is exceptionally complete.

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

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

Schema coverage is 100%, but the description adds valuable meaning beyond the schema: it explains that 'since' accepts both ISO dates and relative shorthand (with examples like '7d', '30d'), and that 'value' can be a ticker or CIK. It also clarifies that 'type' is currently limited to 'company'.

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 'what's new with X' change feed for a company, using specific verbs and resources. It distinguishes itself from the sibling tool 'entity_profile' by explicitly stating when to use each.

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

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

The description provides explicit usage scenarios with example queries like 'what happened to Z this week'. It clearly states when not to use it (when you want a static profile, use entity_profile). It also explains fallback behavior for GDELT→GNews and USPTO soft-failure.

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 persistence behavior beyond annotations: 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours' and scope by identifier. 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?

Four sentences, each adds value: purpose, use case, behavior, and pairing. Front-loaded with the core action.

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

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

Given low complexity (2 params, no output schema), the description fully explains all relevant aspects: persistence, scope, usage intent, and relationships.

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?

Since schema coverage is 100%, baseline is 3. The description adds value through usage pattern explanation and example values like 'subject_property', 'target_ticker', and explains key-value scoping.

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

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

The description clearly states the verb 'Save data' and the resource 'key-value memory' scoped by identifier, and distinguishes from sibling tools 'recall' and 'forget' by naming them and explaining the 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?

Provides explicit usage context with examples (resolved ticker, target address, user preference, research subject) and mentions pairing with recall/forget, but does not explicitly state when NOT to use the tool.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that internal cascading replaces multiple manual lookups, and mentions auto-disambiguation for companies, providing additional context.

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

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

The description is clear but somewhat verbose with extensive examples and type details. It could be more concise, but the structure is logical.

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 parameter set and annotations, the description fully explains purpose, when to use, input format, and return values (including citation URIs). No critical gaps.

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

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

Schema coverage is 100% with descriptions. The description adds examples and explains accepted inputs per type, enriching understanding beyond the basic 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 explicitly states the tool resolves names to canonical identifiers, with clear examples. It distinguishes from siblings like entity_profile by focusing on identifier lookup.

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

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

The description instructs to 'Use FIRST whenever you have a name but need an ID', providing clear when-to-use guidance. It doesn't explicitly mention alternatives but context implies its role as a preliminary step.

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. The description adds context by explaining it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. No contradictions; description enriches behavioral understanding 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 three sentences, well-structured, and front-loaded with the main purpose. Every sentence adds value without fluff.

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

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

Despite lacking an output schema, the description sufficiently explains the tool's operation (probing, ranking) and return values (score, confidence, signal density). It covers the tool's complexity adequately.

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 all parameters described. The description adds extra meaning, such as treating the first entity as the 'subject' for narrative and that context is shared. This goes beyond the schema alone.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probing with ai_visibility_check, ranking by score, and returning a ranked list. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description mentions usage for competitive AI-marketing audits and gives an example question. It implies when to use but does not explicitly state when not to use or list alternatives, though sibling tools provide implicit 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, open-world, idempotent. Description adds value by detailing the fan-out to two services, potential delays (bundlephobia first measurement 5-30s), and graceful degradation with sources_failed list.

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

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

Every sentence is informative and well-organized. No redundant or filler content. Structure flows from purpose to usage to return details to limitations.

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 the return format (summary block, advisory detail, links, alternative versions). It covers parameters, usage, and edge cases (partial failures).

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 explains both parameters and defaults. The description does not add additional semantic information beyond what the schema provides, so baseline of 3 is appropriate.

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

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

The description clearly states the tool performs a composite check for npm packages, listing specific checks (license, advisories, bundle size). It differentiates itself from siblings by being specific to npm package evaluation, not overlapping with other tools.

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

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

Explicitly states when to use (e.g., 'is X safe / popular / small') and provides constraints (NPM only in v1, mentions alternatives for other ecosystems). Also notes partial failure behavior.

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

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

Annotations already declare this as read-only, idempotent, non-destructive. Description adds behavioral context by specifying return fields (names, types, oracle text, etc.) and query capabilities, fully aligning with annotations. No contradiction.

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

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

Two sentences with no wasted words. Front-loaded with purpose and query syntax, followed by return fields. Each sentence earns its place.

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

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

No output schema, but description adequately lists return fields. With read-only annotations, it covers the essential behavior. Lacks pagination or limit details, which are minor gaps.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds value for the 'query' parameter with syntax examples but does not enhance understanding of 'order' or 'unique' beyond the schema.

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

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

The description uses a specific verb ('Search') and resource ('Magic: The Gathering cards') with explicit query syntax examples. It clearly distinguishes from sibling tools like 'get_card' (single card) and 'random_card' by emphasizing structured search.

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 query examples and implies use cases (e.g., 'c:red type:dragon'), but does not explicitly state when to use alternatives like 'get_card' for specific cards or mention exclusions. Clear context but lacks explicit 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 already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds value by detailing the returned verdict types (confirmed, refuted, etc.), actual value with citation, percent delta, and that it replaces multiple sequential calls. 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?

Single well-structured paragraph, front-loaded with usage signals, examples, domain scope, and return structure. Efficient with no fluff, though slightly dense.

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 parameter and no output schema, the description covers purpose, usage context, domain constraints, verdict types, and efficiency gain. Limitations (only US company-financial) are acknowledged, making it sufficiently complete.

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

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

Single parameter 'claim' with natural-language description and concrete examples ('Apple's FY2024 revenue was $400 billion'). Schema coverage is 100%, and description adds useful context beyond the schema.

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

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

The description starts with natural-language query examples, then clearly states the tool does natural-language claim verification against authoritative sources. It specifies the domain (company-financial claims for public US companies) and lists the possible verdicts. This is specific and distinct from sibling tools.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' Domain limitation (company-financial claims) is stated, implying when not to use. Alternatives are not named directly, but sibling list provides context.

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