Foursquare

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

Annotations (readOnlyHint, idempotentHint, etc.) already declare safe behavior. The description adds valuable context: default free model, Anthropic cost pass-through, and return structure. 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 five sentences, front-loaded with the core function, then details, then use cases. Every sentence adds essential information with no redundancy.

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

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

Given no output schema, the description explicitly states the return format. With 4 parameters all described, and clear purpose and usage, the description is fully adequate for correct tool invocation.

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

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

Schema covers all 4 parameters with descriptions (100% coverage). The description adds extra context like default model and pricing, but does not significantly enhance schema meaning beyond repetition.

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 visibility of an entity and scores it (0-100), with specific verb ('probe'). It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on direct LLM queries and per-model scoring.

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 ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use optional parameters (_apiKey for Anthropic). It does not explicitly state when not to use it, but context is clear.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by explaining that the tool routes questions to the appropriate source, fills arguments, and returns structured answers with citation URIs. It could be a 5 if it mentioned that the answer format includes citations or confidence, but it is already very transparent.

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 front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and includes a clear recommendation to start here. It uses bullet-like structured sentences, though the parenthetical aside at the end is somewhat long and could be trimmed for clarity. Still, it earns a 4 for being well-organized and informative with no wasted space.

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, but the description compensates by describing the return format (structured answer with citation URIs) and the routing logic. Given the complexity implied by 5,564 underlying tools, the description provides sufficient context for an AI agent to know what to expect. It also covers the tool's tier compatibility and performance characteristics ('works on every tier, one fast call').

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% (the schema fully documents the 'question' parameter and its aliases), so the baseline is 3. The description does not add semantic information beyond what the schema provides (e.g., it does not explain how to format the question for best results). This is adequate but not exceptional.

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 ask_pipeworx answers factual questions using authoritative data from 5,564 tools across 1,462 verified sources. It explicitly distinguishes itself from siblings by specifying when to use it instead of ask_pipeworx_grounded or deep_research, and includes concrete examples of queries it handles.

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

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

The description provides explicit guidance on when to prefer this tool over web search, with a comprehensive list of domains (SEC, FDA, FRED, etc.). It also clearly states when to step up to alternatives like ask_pipeworx_grounded (for hallucination-resistant answers) or deep_research (for broad/multi-part questions), and when it is not suitable (e.g., breaking news).

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

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive traits. The description adds context about experimental routing improvements and current parity with the stable version, but does not disclose significant behavioral details beyond what annotations imply.

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, focused paragraph that front-loads the purpose and current status. It is efficient but includes a minor redundancy (repeating 'identical universal router' and 'same arguments'). Could be slightly tighter but remains well-structured.

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

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

For a tool with one required parameter, no output schema, and strong annotations, the description covers the beta nature, current state, usage guidance, and sibling relationship. It is mostly complete, though the behavior when a candidate is active is hinted but not fully detailed.

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 mentions 'same arguments' but does not add new meaning beyond the schema's detailed alias descriptions. No extra parameter semantics are provided.

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

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

The description clearly states the tool is a beta version of ask_pipeworx, a universal router with identical tools and arguments. It explicitly distinguishes from siblings by noting it is the experimental edge compared to the stable ask_pipeworx and grounded variant.

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 using this tool exactly like ask_pipeworx when wanting the newest routing, and mentions results are compared to the stable router. While it does not list explicit exclusions, it provides clear guidance on when to choose this over its stable counterpart.

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 annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds significant behavioral context: it extracts answers only from the tool result, returns a structured refusal on failure (with specific reasons), and costs an extra LLM call. This goes well beyond the annotations and provides critical transparency for high-stakes use.

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 (three sentences) yet packed with essential information: purpose, mechanism, return format, use cases, and cost trade-off. It is front-loaded with the core purpose and every sentence adds value.

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

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

Given the tool's complexity (selecting from 5,564 tools across 1462 sources) and the absence of an output schema, the description fully explains the return format including answer, evidence, confidence, source, fetched_at, and explicit refusal reasons. It also covers the behavioral trade-off and appropriate use cases, making it complete for an agent to decide and invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions 'Your question in natural language' but does not add new meaning beyond the schema's existing descriptions of aliases. The parameter semantics are adequately covered by the schema, so the description offers no additional value here.

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

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

The description clearly states the tool's purpose as a 'Hallucination-resistant answer mode for high-stakes reads' and explains that it routes to the correct tool, fetches data, and extracts answers only from the tool result. It distinguishes itself from the sibling 'ask_pipeworx' by emphasizing the extraction step and refusal ability.

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 when to use the tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and provides specific examples (financial verdicts, legal claims, medical lookups, public statements). It also advises preferring 'ask_pipeworx' for casual lookups due to the extra LLM cost, offering clear guidance on 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 readOnly, openWorld, idempotent, and non-destructive. Description adds extensive behavioral details: fan-out patterns, resolver contract with confidence levels, parent event extraction, news fallback fields, safety short-circuits for low-confidence and closed markets, wide-spread tradeability, and cancellation rule parsing. 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 the core purpose but becomes verbose with numerous examples and detailed explanations. While comprehensive, it could be more concise by reducing redundancy in fan-out examples and response shape details.

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

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

Given the tool's complexity (multiple classifiers, fan-out to varied data sources, resolver logic, parent event extraction, news fallback, safety mechanisms, resolution rules), the description covers all necessary aspects. No output schema exists, but the response shapes are thoroughly documented.

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 description adds some nuance (e.g., explaining 'quick' vs 'thorough', and the default for 'include_raw'), but these are already implied by 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 opens with a clear verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It distinguishes from sibling tools (polymarket_edges, polymarket_arbitrage, etc.) by focusing on comprehensive research and evidence gathering for bet evaluation.

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

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

Explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Provides examples of fan-outs per category. Does not explicitly exclude cases or mention alternatives, but context from siblings implies appropriate 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?

Beyond annotations (readOnlyHint, idempotentHint), the description details data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. No contradiction with annotations.

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

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

Description is well-structured: starts with trigger phrases, states core function, provides type-specific details, and ends with result format. Every sentence serves a purpose without unnecessary verbosity.

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

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

The description covers input, behavior, and output format (paired data + citation URIs) adequately. While no output schema exists, the return format is sufficiently described for an agent to understand. Minor omission of exact JSON structure but overall 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 description adds value by explaining the difference between company and drug types, constraining values to 2–5 with examples, and specifying the data pulled for each type. Justification is clear and adds context beyond the schema.

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

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

The description clearly states the tool compares 2–5 entities side-by-side in one call, with specific trigger phrases like 'Compare X and Y' and 'head to head'. It distinguishes itself from sibling tool entity_profile by advocating preference over sequential 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 explicitly tells when to use (comparing entities, head-to-head) and when not to use sequential single-pack lookups. It provides example queries and contexts, leaving no ambiguity about 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral context beyond these: expected timing (15-90s), return format (findings packet with evidence, confidence, gaps, contradictions), depth-specific behaviors (gap recovery, contradiction scan), citation resolvability, and semantic excerpting. 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?

Despite its length, every sentence earns its place. The description is front-loaded with critical prerequisites (account requirement, alternative for unsigned users). It efficiently communicates complex behavior (parallel decomposition, depth levels, citation format, limitations). No redundancy or filler; well-structured for quick comprehension.

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

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

Given the tool has no output schema, the description fully compensates by detailing the return packet (evidence, confidence, source, fetched_at, citation_uri, gaps, contradictions, hop field). It covers prerequisites, timing, edge cases (empty gaps for news topics), and depth-specific differences. No missing information for correct selection and invocation.

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

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

Schema description coverage is 100% with both parameters documented. The description adds significant value beyond the schema: explains the depth enum in richer detail (number of facets, hop behaviors, contradiction scans), and clarifies that the question parameter supports broad/multi-part queries with automatic decomposition. This helps the agent select appropriate values.

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

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

The description clearly states the tool's purpose: grounded multi-source research across structured data sources in one call. It distinguishes itself from siblings like ask_pipeworx (single lookup) and explicitly mentions when to use each. The verb-resource pair ('research structured data sources') is specific and differentiated.

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

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

Provides explicit guidance on when to use this tool vs alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also includes account requirements and fallback for unsigned-in users. Best use cases are clearly stated (e.g., 'compare X and Y's regulatory + financial exposure').

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds details about returning top-N tools with full schemas and curated examples, ready to call directly. 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?

Description is a single dense sentence covering purpose, usage, and output. It is front-loaded but could be more structured for readability. Still efficient.

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

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

Given 6 parameters (mostly aliases), no output schema, the description explains inputs, what results contain, and that they are directly callable. 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 has 100% coverage with descriptions. Description adds value by listing parameter aliases and giving naturals language examples, enhancing meaning beyond schema.

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

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

The description clearly states the tool finds tools by describing data or task, listing many domains. It distinguishes itself from sibling tools (all concrete tools) by being a meta-discovery 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 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available' providing clear when-to-use and order.

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 behavioral traits beyond annotations: soft-fail for patents, fallback from GDELT to GNews, sorted fundamentals, and pipeworx URIs. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint).

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 efficiently packed with examples and details, front-loaded with user intents. Slightly lengthy but justified by the tool's complexity; no wasted sentences.

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

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

Despite no output schema, the description lists all output components (CIK, filings, fundamentals, patents, news, LEI). Parameters are fully covered. Complete enough for a multi-source profile 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%, baseline 3. Description adds semantics: explains 'type' is limited to 'company', 'value' must be ticker or zero-padded CIK, and names not supported. Adds helpful context beyond 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 defines the tool as providing a 'full cross-source profile of a US public company in ONE parallel call' with multiple examples. It distinguishes from siblings like 'resolve_entity' and 'compare_entities' by focusing on a holistic view.

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 ('holistic view') and when not to use (e.g., if only a name, use resolve_entity first). Provides clear input requirements: ticker or zero-padded CIK, not names.

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

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

Annotations already indicate destructiveHint=true, so description adds limited additional behavioral info besides reinforcing sensitive data deletion. No contradiction.

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

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

Two sentences, front-loaded with essential purpose, no filler. Every sentence adds value.

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

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

For a simple tool with one parameter and annotations present, the description fully covers purpose, usage, and context. No gaps.

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

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

Schema covers 100% of parameters with a clear description for 'key'. Description doesn't add extra meaning beyond what schema provides, meeting baseline.

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

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

Clearly states 'Delete a previously stored memory by key' with specific verb and resource. Distinguishes from siblings by mentioning 'remember' and 'recall'.

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

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

Explicitly lists use cases: stale context, task done, or clearing sensitive data. Advises pairing with related tools, providing clear guidance on when to use.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: fetching the page, extracting title/description/key links, and emitting standard markdown format. This complements the annotations without contradicting them. No mention of rate limits or error handling, but the added value is sufficient.

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 immediately conveying the core purpose and output format, followed by a bullet list of use cases. Every sentence adds value, and the structure front-loads critical information.

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

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

Given no output schema, the description adequately explains the output ('a single text blob ready to drop at site-root/llms.txt'). The tool has only two parameters, both documented in the schema. The description covers the core behavior and use cases, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description does not provide additional meaning beyond the schema for the 'url' parameter. For 'max_links', the schema already says 'Maximum number of link entries to include (default 25, max 50).' The description adds no further detail, so it meets the baseline.

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

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

The description clearly states the tool's purpose: generating a production-ready llms.txt file for any URL. It specifies the verb ('generate'), the resource ('llms.txt file'), and the context (AI crawlers indexing the site). This differentiates it from siblings, none of which seem to generate llms.txt files.

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 lists specific use cases (getting a client's site indexed, drafting for own project, auditing competitors) which provide clear context for when to use this tool. It does not explicitly state when not to use it, but the use cases are sufficiently informative for decision-making.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering safety and idempotency. The description adds value by listing return fields, which complements the output schema and provides immediate 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 concise (two sentences), front-loaded with the core action, and efficiently lists return fields without unnecessary words. Every sentence serves a clear purpose.

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

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

Given the simple single-parameter tool, the presence of an output schema, and rich annotations, the description sufficiently covers the tool's functionality and expected behavior. No additional context seems necessary.

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

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

The description adds minimal meaning beyond the schema, which already describes the parameter as 'Foursquare place ID (returned by search_places)'. With 100% schema coverage, the description does not significantly enhance parameter understanding.

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

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

Description clearly states the tool retrieves full place details by fsq_place_id, listing specific fields. It effectively distinguishes itself from sibling tools like search_places and nearby_places by being a detail-fetch for a specific ID.

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 implicitly conveys when to use via the parameter description, which notes the ID comes from search_places. However, it lacks explicit guidance on alternatives or prerequisites, leaving room for improvement.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns specific fields and is scoped to the caller's subscriptions, which is useful but not essential 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: first states the primary action, second provides usage guidance. No extraneous words. Front-loaded 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?

For a simple list operation with one optional parameter and no output schema, the description is complete. It explains what is returned and provides context for when to 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 coverage is 100% and the only parameter 'include_inactive' is well-described in the schema. The description does not add any additional meaning about the parameter, so baseline 3 applies.

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

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

The description clearly states 'List the caller's active subscriptions' with specific verb 'List' and resource 'subscriptions'. It also lists returned fields. While it doesn't explicitly distinguish from siblings like 'subscribe' or 'unsubscribe', the purpose is 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 advises using this tool 'to review what you're monitoring before adding more or to find an id to cancel.' This provides concrete scenarios for use. No mention of when not to use, but the guidance 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 already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, so safety is clear. The description adds behavioral context: sorting by distance, default radius, and return fields (name, categories, address, etc.), and notes unknown category IDs are ignored. This provides useful transparency 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, front-loaded with the primary action and key distinguishing feature. No extraneous words; every sentence adds value. Highly efficient.

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

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

Given the tool has an output schema (implied from context), the description need not explain return values. It covers required inputs, optional parameters with defaults, and return field highlights. Could mention limit default and pagination, but those are in the schema. Overall adequate for a 5-parameter tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description repeats schema info (required lat/lon, optional radius_m default 500, category IDs) but adds no new meaning beyond what the schema already provides. It is consistent and adequate.

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 states 'Return POIs sorted by distance from a lat/lon without a text query,' which is a specific verb (Return) plus resource (POIs) and a distinguishing feature (no text query). This clearly differentiates from siblings like search_places which likely use text queries.

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 lists required and optional parameters clearly but does not explicitly state when to use this tool versus alternatives like search_places. The context is implied but not explicit about exclusions or alternative tool recommendations.

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

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

Annotations offer no safety profile (all hints false), so description carries the burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), the claim_token flow for later retrieval, and the fact that team reads digests daily. This is rich behavioral context beyond what annotations provide.

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

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

The description is long (around 150 words), but every sentence earns its place: purpose, usage conditions, exclusions, content guidance, claim token behavior, rate limit, and quota. It is front-loaded with the core purpose and then flows logically into details, making it dense yet structured rather than padded.

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

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

Given there is no output schema and annotations reveal nothing, the description is remarkably complete. It covers when to use, what to include in the message, the claim_token lifecycle, rate limiting, and cost exemption. The only unspecified aspect (exact response format) is reasonably left to the schema, and the description even notes the 'other' type implicitly via the enum.

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%, giving every parameter a description. The tool description adds extra value by mapping the type enum values to usage cases (bug/feature/data_gap/praise), instructing users to 'Describe the issue in terms of Pipeworx tools/packs' for context, and explaining the claim_token round-trip. This goes beyond the schema's literal definitions.

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

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

The description opens with a clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It lists the exact feedback categories (bug, feature/data_gap, praise), which also differentiates it from sibling tools like ask_pipeworx or deep_research that are for research, not 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?

Provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion and alternative: if the tool comes from a different MCP server, 'file it with that server instead.' The 'Not sure? Pipeworx tool names are the ones this connection lists' clarifies scope.

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 value by explaining data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). No contradictions.

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

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

Three sentences plus use-case list. No redundancy; each sentence adds unique information (what, how derived, use cases). Well-structured and front-loaded.

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

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

No output schema, but description clearly describes return value (top tools, top packs, total call volume) and explains caching and data source. Sufficient for agent to understand behavior and output.

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

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

Only one parameter 'window' with enum. Schema covers 100%, description adds semantic guidance: shorter windows for hot trends, longer for steady-state demand. Enhances understanding beyond enum values.

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

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

Clearly states it returns top tools, top packs, and total call volume over recent windows. Distinguishes from siblings by focusing on trending data from pipeworx calls, with specific use cases listed.

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

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

Provides three explicit use cases (discovering hot data sources, confirming canonical tools, aligning use case with agent needs). Does not include when-not-to-use but context is clear enough for an agent.

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

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

Discloses key behaviors beyond annotations: scans top 200 markets, uses Jaccard similarity threshold, partition filter with placeholder detection, fill check against live CLOB depth. No contradiction with readOnlyHint, openWorldHint, or idempotentHint.

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 and front-loaded with the main purpose. While information-dense, every sentence adds value. Could be slightly more concise but remains well-organized.

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 response fields (opportunities array with subfields, partition_check object, fill check result). Covers complex behaviors like semantic anchoring and placeholder filtering completely.

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

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

Both parameters have schema descriptions (100% coverage). The description adds significant value: explains accepted formats (slugs or full URLs for event, seed questions for topic), and clarifies the behavioral difference between modes.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by specifying the exact detection methods.

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 describes three usage modes: no args for trending scan, event slug for specific market, and topic for cross-event scanning. Provides examples and recommendations (event mode recommended for specific markets). Also warns when not to trade based on fill check results.

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

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

The description goes far beyond the annotations, detailing the internal models (crypto_price, news_momentum, partition_overround, concentrated_longshot), caching behavior (1h KV-level), and response structure. It explains edge calculations, slippage handling, and diagnostic fields, providing rich behavioral context that helps the agent understand the tool's inner workings.

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

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

The description is lengthy but efficiently packed with essential information. It is front-loaded with the main purpose and then progressively details models, response format, and knobs. Every sentence adds value, but the density could be slightly reduced without losing clarity. Still, it is well-structured and avoids 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?

The description comprehensively covers all aspects needed for an agent: purpose, usage, behavioral details, parameter explanations, response structure (including diagnostics), and caveats (Fed bets excluded, caching). No gaps remain, despite 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?

With 100% schema coverage, the baseline is 3, but the description adds significant practical guidance for every parameter. For example, it explains slippage_pp with realistic values and context (zero fees but 20-50bp typical cost), and provides concrete examples for min_liquidity and max_spread_pp. This enhances the agent's ability to set optimal parameters.

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

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

The description clearly states the tool's purpose: scanning Polymarket markets for opportunities where Pipeworx data disagrees with market price. It explicitly positions it as a discovery tool for agents, distinguishing it from other tools like polymarket_arbitrage or polymarket_edge_tracker by focusing on edge detection across multiple model families.

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 (discovering betting opportunities) and explains the three opportunity segments with their triggers. It also notes when certain opportunities are excluded (Fed bets due to data reliability). However, it does not explicitly contrast with sibling tools or state when not to use it.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. The description adds rich behavioral details: data source, response structure (tracked, expired, snapshot_dates), and limits (60-day TTL). No contradictions.

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

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

Description is thorough but efficiently packed; front-loaded with key question. Slightly verbose but each 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 no output schema, the description fully compensates by detailing response fields and data behavior. Complete for a telemetry 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%; description adds marginal context (e.g., 'default 14, max 30') but mostly repeats schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry from daily snapshots. It distinguishes from siblings like 'polymarket_edges' by focusing on time-series decay analysis.

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

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

The description implicitly guides when to use by answering 'how long has this edge existed and is it shrinking?' It lacks explicit when-not or alternatives, but context makes usage 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 readOnly, openWorld, idempotent, non-destructive. Description adds: requires one of market/event, default sizes, walk-ladder behavior, return fields (top_of_book, vwap, verdict, capture_ratio, thin_legs, etc.), and forced_directional_risk naming. 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 long but front-loaded with purpose. Uses all-caps for modes and structured sections. Every sentence adds value but could be more concise; some repetition of details.

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

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

No output schema, but description fully explains complex returns: top_of_book, vwap, slippage, shares_filled, verdict, capture_ratio, profit_usd, per-leg fill, thin_legs, max_clean_notional, forced_directional_risk. Covers both modes comprehensively.

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

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

Schema description coverage is 100% but description adds context: default values, interpretation of size_usd for buys vs sells and basket vs single, auto default for side in basket mode. Enhances understanding beyond 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?

Clearly states it checks realizable vs theoretical edge against live order book depth. Distinguishes single-market and basket modes with specific verbs like 'walks the ladder', 'returns verdict'. Differentiates from sibling tools by specifying it should be used before acting on polymarket_arbitrage signals or trades > $500.

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 provides when to use: before acting on arbitrage signals or trades > $500. Explains consequences of partial basket fills converting arb to unhedged directional position. Implicitly names alternatives (polymarket_arbitrage, polymarket_edges) and scenarios where tool is critical.

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 goes beyond by detailing safety fields (compatibility_warning, temporal_alignment, skipped types) and explaining their meaning, providing rich behavioral context.

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

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

The description is well-structured with headings and bullet-like sections, but it is somewhat verbose. Every sentence adds value, though some could be tightened without losing clarity.

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

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

Despite no output schema, the description explains the response structure (leg-by-leg prices, top_spreads_pp, safety fields) and the meaning of each safety field. It fully covers the tool's complexity and return behavior.

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

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

Schema coverage is 100%, but the description adds value: expands on topic options, explains that explicit tickers override topic mappings, and provides examples. This enhances understanding 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 computes cross-venue spreads between Kalshi and Polymarket for the same question, and distinguishes two modes (topic shortcuts vs explicit tickers). It does not explicitly differentiate from sibling tools like polymarket_arbitrage, but the purpose 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 guidance on when to use each mode, warns that most pre-mapped topics return compatibility warnings, and states pre-mapped ≠ tradeable. It does not explicitly exclude use cases (e.g., single-venue data), 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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by explaining scoping to identifier (anonymous IP, etc.) and pairing, which annotations don't cover. No contradictions.

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

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

Three sentences pack all needed info: purpose, usage, scope, and sibling relation. No redundancy, front-loaded with core action.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers use cases, behavior, and boundaries. 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?

The only parameter 'key' is fully described in the schema (coverage 100%). The description adds context about omitting it to list keys, which goes beyond the schema. Baseline 3 with one extra point for added clarity.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys. It uses specific verbs like 'Retrieve' and 'list', and distinguishes itself from sibling tools like 'remember' and 'forget' by indicating 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 tells when to use (look up stored context) and how (omit key to list all). Also mentions pairing with remember and forget, providing alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context about returned fields (source, citation_uri, raw payload) and the mark_read side-effect, which is consistent 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?

Reasonably concise at 4 sentences, front-loaded with purpose. Could be slightly more structured with bullet points, but still 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?

For a read-only list tool with no output schema, the description thoroughly covers returned data fields, optional filtering, mark_read behavior, and polling suitability. Leaves no major gaps for usage.

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 giving examples for 'type' (sec_8k) and explaining the effect of 'mark_read'. 'limit' and 'unread_only' are not explicitly mentioned but are covered by 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 opening verb 'Pull' clearly identifies the action, and 'fired events from your subscription feed' specifies the exact resource. The description distinguishes itself from siblings like 'list_subscriptions' by focusing on events that have been triggered.

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 that polling works fine and provides an alternative URL for scripts/dashboards, giving usage context. However, it does not explicitly state when not to use this tool versus siblings.

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

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

The description discloses the tool fans out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO), including fallback and soft-fail details. It also describes the return structure and citation URIs, adding 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?

The description is a single paragraph that efficiently conveys purpose, usage, sources, and return format. It is front-loaded with example queries and every sentence adds value.

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

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

Despite no output schema, the description adequately explains the return structure (changes grouped by source, total_changes count, citation URIs). It covers source behaviors, parameter details, and alternative tool usage, making it complete for this complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds examples for 'since' format (ISO date and relative shorthand) and recommends typical values. It also clarifies that 'value' can be a ticker or CIK. This extra guidance merits a 4.

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

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

The description clearly states the tool provides a change feed for a company over a time window, with examples of user queries. It distinguishes itself from the sibling 'entity_profile' tool by contrasting use cases.

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

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

The description explicitly tells when to use this tool versus 'entity_profile', and explains the fallback behavior between GDELT and GNews. It also provides a typical usage recommendation for the 'since' parameter.

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?

Given annotations declare idempotentHint=true and no destructiveHint, the description adds valuable context: key-value scoping by identifier, persistence for authenticated users, 24-hour retention for anonymous sessions. 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, zero wasted words. The description is front-loaded with the core purpose, followed by usage context and behavioral details. Perfectly structured for AI consumption.

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 covers what the tool does, its scope, persistence behavior, and relationship to siblings. No gaps remain for the agent to infer incorrectly.

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 parameter descriptions. The description adds value by providing example keys and clarifying that the value is free-text, but the schema already captures the essential meaning.

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

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

The description starts with a clear verb ('Save data') and resource ('the agent will need to reuse later'), and explicitly separates from sibling tools 'recall' and 'forget', making the tool's purpose unmistakable.

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

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

The description states exactly when to use this tool ('when you discover something worth carrying forward'), provides concrete examples, and contrasts with 'recall' and 'forget' for retrieval and deletion.

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

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

Annotations already indicate read-only and idempotent behavior, but the description goes well beyond by detailing internal cascading endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, source-labelled identifiers, and explicit handling of unresolved identifiers. This is rich behavioral context that materially aids an agent.

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

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

The description is long and dense, but every sentence contributes value, from the query examples to the detailed breakdown of supported types and error behavior. It is front-loaded with examples and the core purpose. Some structure (e.g., bullets) could improve readability, but the content is well-organized.

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, so the description must convey what the tool returns. It explains the identifiers for company (CIK, ticker, LEI, FIGI) and drug (RxCUI, ingredient, brand) plus the citation, and it describes unresolved identifier handling and degradation. It lacks an explicit output structure but is complete enough for a complex tool.

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

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

The schema covers the two parameters with descriptions and an enum, but the tool description adds meaningful semantic detail: it specifies ISIN as an accepted input for company (not mentioned in the schema) and clarifies that drug accepts brand or generic names with examples. This goes beyond the schema's 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 explicitly states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input,' with clear examples like 'What's the ticker for…'. It distinguishes itself from sibling tools by focusing on name-to-ID resolution and lists supported types (company, drug), leaving no ambiguity about its purpose.

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

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

The description gives direct usage guidance: 'Use FIRST whenever you have a name but need an ID.' This provides clear context and a strong precondition. However, it does not explicitly state when not to use the tool or name alternatives, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds that it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, signal density. This explains the internal process and output format 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?

Three sentences: first states purpose, second explains process, third gives use case and output. Front-loaded, no wasted text. 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 no output schema, the description explains return format (ranked list with score, confidence, signal density). For a read-only aggregation tool with good annotations, this is sufficient. Doesn't cover error cases or limits, but overall complete enough for effective use.

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

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

Schema covers 100% of parameters with descriptions. The description adds meaning: first entity is treated as subject for narrative, rest as competitors. This goes beyond schema, aiding correct usage. However, it doesn't detail the implications of models or _apiKey beyond what schema says.

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, using ai_visibility_check probes and ranking. This specific verb+resource distinguishes it from the sibling 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?

It explicitly mentions use case: competitive AI-marketing audits, with an example question. It implies when to use (comparing multiple brands) but does not explicitly state when not to use or name alternatives, though ai_visibility_check is a clear alternative for single entity inspection.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds valuable behavioral details: partial failures degrade gracefully, bundlephobia can take 5-30s on first measurement, and error sources are listed. 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 dense and well-structured, front-loading the purpose. It could be slightly more concise, but every sentence adds value. The mention of partial failures is important but adds length.

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

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

Given the tool's complexity (composite check, multiple services, partial failures), the description covers the return values (summary block, advisories, links, alternative versions) thoroughly. No output schema makes this essential, and it's well-handled.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds minor context (scoped packages accepted, version defaults to latest), which reinforces but doesn't substantially extend the schema.

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

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

The description clearly states the tool's purpose: a composite check for npm packages encompassing license, advisories, bundle size, etc. It uses specific verbs like 'fans out' and distinguishes itself from siblings by its domain (npm packages).

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

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

The description provides explicit guidance on when to use this tool ('is X safe / popular / small') and notes ecosystem limitations (NPM only in v1, others via deps.dev:version directly). This helps avoid misuse.

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 a safe, read-only, idempotent operation. The description adds value by specifying the exact return fields and highlighting a constraint on the `categories` parameter (must be numeric IDs from prior results). There is no contradiction with annotations.

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

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

The description is extremely concise, consisting of two sentences that front-load the primary purpose and then list the return fields. 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?

Given the tool's complexity (8 parameters, output schema present, rich annotations), the description covers the core functionality and return format adequately. It does not discuss sorting behavior or pagination, but those are documented in the 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 detailed descriptions for each parameter, including examples and constraints (e.g., `categories` explanation is thorough). The tool description does not add new meaning beyond that, so the 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 it searches Foursquare places and specifies the required combination of query and location anchor. It also lists the output fields. However, it does not explicitly distinguish from the sibling tool `nearby_places`, which might serve a different use case (e.g., query-less nearby 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?

The description explains that either `near` or `latitude`+`longitude` must be used with `query`, providing some usage context. But it offers no guidance on when to prefer this tool over `nearby_places` or other sibling tools, and no exclusions or prerequisites are mentioned.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds rich behavioral details: embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flag. 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 concise and well-structured: first sentence states purpose, then usage guideline, then technical details. Every sentence adds value with no redundancy.

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

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

No output schema, but description adequately explains return values: 'top-N passages with character offsets and similarity scores', plus each passage has an offset for verification. Covers limits, pairing, and truncation behavior. Complete for a search tool.

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

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

Schema coverage is 100%, with each parameter having a description. Description reinforces and expands: 'text' gets max char limit, 'query' gets examples, 'limit' gets default range. Adds marginal value beyond schema, elevating from baseline 3.

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

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

Description clearly states it performs semantic search inside a fetched record, using specific verbs ('search inside') and resource ('a fetched record'). It distinguishes from sibling tools like ask_pipeworx_grounded by describing 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?

Explicitly provides usage guidelines: 'Use when the record is too big to cram into the prompt — search_within saves context'. Also mentions pairing with ask_pipeworx_grounded for grounding over relevant passages, clarifying alternative approaches.

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

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

The description adds significant behavioral context beyond annotations, such as requiring OAuth, delivery channel limitations (SMS 10/day cap, webhook auto-disable after failures), and the always-on feed. It does not contradict annotations. However, the idempotentHint annotation suggests idempotency, but the description says 'Returns the new subscription id' implying each call creates a new subscription, which could be clarified. Nevertheless, the description is largely transparent.

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, starting with the main action, then requirements, supported types, and delivery options. Every sentence adds value without redundancy. It is concise yet thorough, fitting 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?

Despite no output schema, the description mentions the return value (subscription id). It covers prerequisites, supported types, delivery channels with limitations, and error conditions (webhook auto-disable). For a tool with nested objects and multiple options, the description is highly complete and leaves few gaps for the 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, but the description adds substantial meaning by providing concrete examples for each subscription type (e.g., sec_8k with ticker and items codes, polymarket_edge with topic). It also explains delivery parameters in detail, including webhook signing and phone verification requirements, far exceeding 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 creates a proactive monitoring subscription to a live-data event stream. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation. It gives specific examples of subscription types and delivery channels, 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 provides clear guidance on when to use this tool (for proactive monitoring) and prerequisites (requires a Pipeworx OAuth account; anonymous or BYO accounts cannot persist subscriptions). It also lists supported types with examples. However, it does not explicitly state when not to use it or directly contrast with siblings like list_subscriptions or recent_alerts, which slightly reduces completeness.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context that the tool returns example questions with tool+argument shape, and that it can be called with no arguments or a topic. 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 fairly long but well-structured with examples, usage guidance, and expected output. Every sentence adds value, though it could be slightly more concise. It is front-loaded with the core purpose.

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

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

Given the simplicity of the tool (one optional parameter, no output schema), the description is fully complete. It explains the return format (category-bucketed example questions with tool+argument shape) and covers all necessary context for an agent to use it correctly.

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

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

Schema coverage is 100% with a description for the 'topic' parameter. The description adds value by listing example topic values ('finance', 'pharma', etc.) and explaining that omitting the argument gives a full spread, which 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 that the tool returns category-bucketed example questions for onboarding, with a specific verb ('returns') and resource ('example questions'). It distinguishes itself from siblings as the entry point for new users.

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

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

The description explicitly states to use this tool FIRST when you don't know what Pipeworx can do, and to learn how to call meta-tools. It provides clear context for when to use it, though it doesn't explicitly list alternatives or when not to use it.

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

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

The description adds valuable behavioral details beyond annotations: soft deactivation (row not deleted), historical events remain available via recent_alerts. This complements the annotations (destructiveHint=false, idempotentHint=true).

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 concise sentences: purpose, ownership, effect. No wasted words, front-loaded with core action.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, constraints, and side effects. It also references a sibling tool for further context.

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

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

Schema coverage is 100%, so the schema already documents the id parameter. The description does not add new parameter meaning, meeting 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 explicitly states 'Cancel a subscription by id' and clarifies the action (deactivation vs deletion). It 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?

Ownership enforcement is clearly stated ('you can only cancel your own subscriptions'), guiding when to use. However, no explicit alternative or when-not-to-use guidance is provided.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses critical behavioral nuances: the exact meaning of 'could_not_verify' (check did not happen, not evidence, must not be shown as one), 'unsupported' semantics, and error structure (verification_error{stage,detail}). It also reveals the routing behavior between structured SEC data and the grounded pipeline. This is exceptional 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 long but dense with useful information. It front-loads trigger phrases and a high-level purpose, then provides routing details, verdict enum, citation info, and critical failure semantics. Every sentence adds value, but it could be tightened; the enumeration of verdict types and examples slightly lengthens it without losing necessity.

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 specifies expected return values (verdict types, actual value with citation, reasoning) and handles failure modes (could_not_verify, unsupported) with actionable guidance. For a complex tool with two parameters, it explains routing, error semantics, and usage constraints, making it complete for an agent to decide and invoke.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema: it explains that the claim is natural-language e.g. sentences, and that tolerance_pct overrides the implied tolerance, with a default capped at 5 and a purpose for hallucination detection (1–2%). This adds practical guidance on how to set the parameter.

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

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

The description opens with concrete natural-language query patterns and a clear verb ('validate claim') and resource ('against authoritative sources'). It explicitly scopes to factual claim verification and distinguishes itself from sibling tools by describing its consolidated pipeline that replaces 4–6 sequential calls, making it clearly a claim-checking tool rather than a search or research 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 gives a direct usage instruction: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates between company-financial claims (SEC path) and all other claims (grounded pipeline), providing clear context. However, it does not explicitly name alternative tools to use instead, only implicitly excluding them via its specialized purpose.

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