Isin

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context: default model (Workers AI Llama-3.3-70b, free), optional Anthropic probe with BYO key, and the return structure (per-model score, confidence, signals, raw_response). 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 three sentences, front-loaded with purpose, then details on models and return structure. No wasted words. Every sentence is informative.

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

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

Given no output schema, the description explains the return format (per-model object + combined view). It covers key behavioral traits and parameter nuances. Could be slightly more detailed on return fields, but it is sufficient for an agent. Complexity is moderate, and the description is nearly complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond schema: explains default model and the purpose of _apiKey ('BYO key — you pay Anthropic directly') and context ('Helps disambiguate common names'). This adds value despite full schema coverage.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and outputs visibility scores (0-100). The verb 'probe' and resource 'LLMs' are specific. However, it does not explicitly differentiate from similar sibling tools like 'scan_competitor_ai_presence', leaving some ambiguity about when to choose this over alternatives.

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

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

The description gives use-case hints ('AI-marketing audits, pre-launch brand checks, competitive monitoring') but does not explicitly state when to use or not use this tool, nor does it mention alternative tools. The guidance is implied but lacks explicit exclusions or comparisons.

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=false. The description adds context about routing to many tools, filling arguments, and returning structured answers with stable pipeworx:// citation URIs. It does not contradict annotations and provides meaningful behavioral detail beyond the structured fields.

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

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

The description is front-loaded with the key preference and uses case. It is well-structured with examples and differentiation from siblings. However, it is slightly verbose and could be trimmed to improve conciseness without losing clarity.

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

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

Given the complexity (6 params, 1 required, no output schema), the description is highly complete. It covers tool purpose, usage context, examples, when to use alternatives, and behavior. No output schema exists, so description appropriately focuses on inputs and functionality.

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

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

Schema description coverage is 100%, with all six parameters documented including aliases for 'question'. The description does not add additional semantic detail beyond what the schema provides, but baseline 3 is appropriate when schema covers everything.

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

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

The description clearly states the tool routes questions to 4,500 tools across 1,137 sources, handles factual queries about real-world entities, and returns structured answers with citation URIs. It distinguishes from siblings like ask_pipeworx_grounded and deep_research by specifying 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 advises 'PREFER OVER WEB SEARCH' and gives detailed when-to-use guidance: for SEC filings, FDA data, economic stats, etc. Provides examples and states 'START HERE for most questions'. Also tells when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds: costs one extra LLM call, returns structured success/refusal responses, and details refusal reasons. 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?

Well front-loaded with key behavior and purpose, but slightly verbose (3 sentences). Each sentence earns its place, but some minor redundancy exists (e.g., listing refusal reasons twice).

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

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

Given tool complexity (4,500 tools, 1137 sources) and comprehensive annotations, the description fully covers: result format, refusal reasons, cost tradeoff, and usage context. No output schema needed as return values are described.

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 described as alias for 'question'. Description merely restates 'Your question in natural language' and lists aliases, adding no semantic value beyond the schema.

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

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

Description clearly states it is a hallucination-resistant answer mode for high-stakes reads, explicitly contrasting with ask_pipeworx. It specifies the verb 'extracts answer using ONLY what the tool result contains' and distinguishes itself by name and use case.

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

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

Provides explicit when-to-use (quoted/cited/acted-upon answers, high-stakes domains) and when-not-to-use ('prefer ask_pipeworx for casual lookups'), directly naming the alternative tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds extensive behavioral details: market resolution, classification, fan-out, evidence packet, safety checks (low-confidence short-circuits, closed markets, wide spreads), resolution-rule risk, and news fallback. No contradiction with annotations.

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

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

The description is long but well-structured with capital-letter section headers (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every sentence adds value, but some sections could be more concise. However, given the tool's complexity, thoroughness is warranted.

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 all aspects of the tool's behavior: input resolution, classification, fan-out examples, response shapes, resolver contract, parent event extractor, news fields, safety checks, wide spreads, and resolution-rule risk. Without an output schema, the description fully explains return values and edge cases, making it complete for an agent.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema. It explains that 'market' can be a slug, URL, or question text; 'depth' values are clarified (quick=2-3 sources, thorough=full fan-out); 'include_raw' default false is explained with rationale about response size. This goes beyond basic parameter names.

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

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

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

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

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

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides usage context but does not explicitly state when not to use it or compare with alternatives. However, the detailed examples and caveats (e.g., low-confidence matches, closed markets) give practical guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: it handles off-calendar fiscal years, sorts results by primary metric, returns citation URIs, and specifies data sources for each entity type. 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 a single dense paragraph but front-loaded with example queries. Every sentence adds value: use cases, data sources, sorting behavior, return format. It is efficient but could be slightly more concise by grouping related information.

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

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

Given the tool's complexity (two entity types, multiple data sources) and no output schema, the description covers key aspects: what data is retrieved, sorting, and citation URIs. It is complete enough for an agent to understand the tool's capabilities, though it could mention error handling or limitations.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema by explaining what data each 'type' pulls (financial metrics for company, adverse events for drug), entity count constraints, and format examples. This helps the agent understand the parameters' semantics beyond the schema descriptions.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, with specific verbs like 'compare', 'rank', 'head to head'. It distinguishes from siblings by emphasizing it replaces sequential lookups and provides data sources (SEC EDGAR/XBRL for companies, FAERS for drugs).

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

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

The description explicitly advises 'ALWAYS PREFER over sequential single-pack lookups' and explains when to use (comparing entities). It implies alternatives are sequential lookups, but does not list specific sibling tools as alternatives. The guidance is clear but lacks explicit exclusion criteria.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds value by explaining the conversion logic and default country, but does not disclose error handling or behavior for invalid CUSIPs.

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: one sentence stating the action followed by an example. No redundant information.

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

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

The description covers input, conversion logic, and an example. For a simple tool without output schema, this is mostly complete, though it could mention behavior for invalid inputs.

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

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

Schema coverage is 100%, but the description adds meaning: explains the country default, role in conversion, and provides an example, which goes beyond the schema's field 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 converts CUSIP to ISIN by prefixing country code and appending check digit, with an example. However, it does not explicitly distinguish this from sibling validation tools.

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

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

The description implies the tool is for conversion, but does not provide explicit guidance on when to use vs alternatives like validate_cusip or validate_isin, nor does it mention when not 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 declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint false. The description adds significant behavioral context beyond annotations: it explains the tool runs in parallel across 4,500 tools, returns a findings packet with citations and gaps[], and has a 15-60s latency. It also clarifies that results are grounded in structured data, not open-web search, which complements the openWorldHint.

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 critical info (account requirement and fallback tool) in the first sentence. Despite its length, every sentence adds value: usage guidelines, core functionality, examples, limitations. The structure logically flows from prerequisites to core to caveats, with no redundancy. It is concise relative to the information density.

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 covers return values (findings packet with evidence, confidence, source, citation, gaps[]). It also addresses limitations (empty gaps for non-catalog topics), time expectations (15-60s), and prerequisites (account, paid plan for thorough). This is complete for an agent to correctly select and invoke 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% (both parameters described). The description adds meaning beyond the schema: for 'depth', it explains the enum meanings (quick=3, standard=5, thorough=8) and that standard is default. For 'question', it clarifies that natural language, broad/multi-part queries are appropriate and that decomposition is the tool's purpose. This provides actionable context for the agent.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1137 STRUCTURED data sources' in one call. It uses specific verbs like 'decomposes', 'routes', and 'returns', and distinguishes from siblings like ask_pipeworx by noting deep_research is for broad/multi-part structured data queries, not single lookups or breaking news.

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 this tool vs alternatives: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It also mentions account requirement and depth tier constraints, providing clear guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns top-N most relevant tools with names, descriptions, and full input schemas with curated examples, and that results are ready to call directly. No contradictions.

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

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

The description is concise (two sentences) and front-loaded with the core purpose. Every sentence adds value: defines purpose, enumerates domains, explains output, and gives usage advice. No unnecessary words.

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

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

Given 6 parameters and no output schema, the description adequately explains the return value (top-N tools with schemas and examples). It covers the overall behavior well, though missing details on edge cases like no results or pagination, which are minor for a discovery 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. Description only mentions 'query' field and limit (default 20, max 50), which is already in the schema. The schema itself provides detailed param descriptions including aliases, so description adds minimal extra 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 uses a specific verb 'Find tools' and a clear resource 'data or task', enumerating many example domains (SEC filings, financials, etc.). It distinguishes from siblings by being the discovery tool, while siblings like search_within and deep_research serve different purposes.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides context for when to use (browse, search, look up, discover), but no direct alternatives mentioned, though sibling names imply differentiation.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds that it fans out across multiple sources, returns specific fields (CIK, filings, fundamentals, patents, news, LEI), notes patents API sunset condition, and mentions parallel call. No contradictions with annotations.

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

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

The description is somewhat long (3 sentences) but well-structured: starts with examples, then purpose, then details. Every sentence adds value. Could be slightly more concise, but effective.

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

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

Given no output schema, the description thoroughly lists return components (cik, recent_filings, fundamentals, patents, news, LEI) with details on sources and status. Mentions limitations (patents API sunset) and parallel execution. Fully prepares an AI agent for tool 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 3. Description reinforces that type is 'company' and value is ticker or CIK, adds context that names are not supported, and clarifies zero-padded CIK format. Adds value beyond schema.

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

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

The description starts with clear use-case examples ('Tell me about X', 'research Acme') and states 'full cross-source profile of a US public company in ONE parallel call'. It explicitly differentiates from siblings like resolve_entity (for name resolution) and compare_entities (for comparison).

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

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

The description says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', provides explicit input formats (ticker or CIK), and says 'names not supported (use resolve_entity first if you only have a name)'.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true, so the agent knows the tool mutates data and is idempotent. The description adds context about when to use but does not disclose additional behavioral traits 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, no wasted words. Front-loaded with the core action, then usage guidelines. 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?

For a simple tool with one required parameter, no output schema, and clear annotations, the description is complete. It covers purpose, usage, and pairing with related tools.

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

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

Schema coverage is 100%, and the description does not add meaning beyond the schema's description of the 'key' parameter. Baseline score of 3 is appropriate since the schema already documents the parameter adequately.

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

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

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

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

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

Provides explicit usage scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' Also explicitly pairs with 'remember' and 'recall,' giving clear guidance on when to use this tool versus 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?

Describes the fetch-extract-emit process, adding behavioral context beyond annotations. Annotations already declare read-only, idempotent, non-destructive; description aligns and adds details on content extraction and output format.

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

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

Three sentences, no redundancy. Front-loaded with purpose, then mechanism, then use cases. 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?

Simple tool with 2 parameters and no output schema; description covers what it does, how it works, and what the output looks like ('single text blob ready to drop at site-root/llms.txt'). Sufficient for correct agent invocation.

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

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

Schema coverage is 100% with clear property descriptions. Description adds minimal additional meaning (e.g., 'Full URL' reinforces but doesn't extend beyond schema). Baseline 3 is appropriate.

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

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

Description clearly states verb 'generate', resource 'llms.txt file for any URL', and output format. Distinguishes from siblings by mentioning AI crawlers and specific use cases (client, own project, competitor audit).

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?

Lists three explicit use cases ('useful for:'). Lacks explicit when-not-to-use or alternatives like 'ai_visibility_check', but provides clear context for when the tool is appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false. The description adds value by specifying the returned fields and implying default behavior (active only), going beyond annotations without contradicting them.

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

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

Two focused sentences: first states purpose and outputs, second gives usage guidance. No redundant information.

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

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

Given one optional parameter, no output schema, and annotations covering safety, the description sufficiently explains the tool's purpose, return fields, and use case. Complete for its complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add additional meaning beyond the schema's description of 'include_inactive' parameter, but the schema itself is 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 clearly states the verb 'List', resource 'subscriptions', and scope 'caller's active'. It also enumerates returned fields, distinguishing it from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

The description provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel'. It does not explicitly state when not to use, but the context is clear.

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

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

Annotations show readOnlyHint=false, destructiveHint=false. The description adds behavioral details: rate-limited to 5 per day, doesn't count against tool-call quota, team reads digests daily, and it's free. No contradictions; all disclosures are accurate and add value beyond annotations.

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

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

The description is front-loaded with the core purpose, followed by clear usage instructions. Every sentence adds value without redundancy. The structure is logical: purpose, when to use, what to include, how team uses feedback, limitations, and cost. No 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?

Given the tool's simplicity (feedback submission) and no output schema, the description is complete. It covers when to use, what to include, rate limits, cost, and how feedback is processed. The nested context object is well-documented in the schema, so no additional description needed.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description does not repeat parameter details but adds context (e.g., emphasize type enum usage, message constraints). It provides guidance that complements the schema, earning a score above 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 title and description clearly state the tool is for sending feedback about Pipeworx tools. It specifies the action (tell team something is broken/missing/praise) and resource (Pipeworx team). It distinguishes from sibling tools, none of which are feedback-related, making its purpose unique and clear.

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

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

The description explicitly states when to use the tool (bug, feature, data_gap, praise) and provides clear usage rules: describe in terms of tools/packs, don't paste end-user prompt. It also mentions rate limits (5 per identifier per day) and that it's free, guiding the agent on 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?

The description adds significant behavioral context beyond annotations: it states the tool is derived from CF analytics-engine, contains no PII, only (pack, tool, count), and is cached 5min-1h depending on window. This aligns with annotations (readOnlyHint, idempotentHint) and provides valuable 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 concise and well-structured: a clear opening statement, bullet-pointed use cases, and additional technical details. Every sentence adds value without unnecessary repetition.

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

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

Given the tool's simplicity (one optional parameter, full schema coverage, rich annotations), the description fully explains the data returned (top tools, packs, call volume) and caching behavior. It is sufficiently complete for an agent to select 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?

The input schema already provides a comprehensive description for the 'window' parameter with guidance on short vs long windows. The tool description does not add new semantic meaning beyond what the schema provides.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window' and specifies the data source and use cases. It distinguishes from siblings like 'discover_tools' by focusing on trending data from other agents.

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 three explicit use cases (discovering hot data sources, confirming popular tools, aligning with agent needs), providing clear context for when to use. However, it does not explicitly mention when not to use or compare to 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 indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral context: explains modes, checks performed (monotonicity, partition_sum), output structure (opportunities[], partition_check), fill check logic, semantic anchor (Jaccard similarity), partition filter, and trade advisory. 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 verbose but well-structured, starting with the requirement, then explaining modes and details. Every sentence adds value given the complexity, though it could be slightly more concise 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 details the response structure (opportunities[] with gap_pp, suggested_trade, reasoning; partition_check; fill check fields). It covers prerequisites, limitations, and a sibling tool reference, making it complete for a complex analysis 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%, but the description adds meaning: for 'event', it clarifies it accepts slugs and full Polymarket URLs; for 'topic', it explains it searches for related events. It also states the mutual exclusivity requirement, adding 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between event mode (single-event) and topic mode (cross-event), providing specific examples like 'fed-decision-may-2026' for event and 'Fed rate decision' for topic. This makes the purpose precise and distinct from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description explicitly requires one of `event` or `topic`, warning that calling with no args fails. It recommends event mode for specific markets and topic mode for cross-event scanning, and directs users to polymarket_fill_risk for custom sizing, providing clear guidance on when to use this tool and alternatives.

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

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

The description meticulously details the tool's behavior beyond annotations: it explains the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), response structure, caching (1h KV-level), and output fields like edge_pp_net and kelly_fraction. Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are fully consistent and enhanced by the description. No contradictions.

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

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

The description is comprehensive but verbose, spanning multiple paragraphs with technical details (e.g., alpha values, funnel counters). While well-structured with sections, it could be more concise. Front-loading the purpose helps, but the length may deter quick scanning. A more streamlined version would improve conciseness.

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

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

Given the tool's complexity (9 parameters, no output schema, three model families), the description is exceptionally complete. It explains the response top-level structure, field semantics (edge_pp_net, kelly_fraction, liquidity), diagnostics for empty segments, and even footnotes on Fed bets. This compensates fully for the missing output schema and guides correct 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?

The input schema already provides 100% coverage with detailed descriptions for all 9 parameters. The main description adds value by explaining the tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) in context, but does not significantly augment the schema's parameter documentation. Per the guidelines, baseline 3 is appropriate since schema does the heavy lifting.

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 top Polymarket markets to return opportunities where Pipeworx data disagrees with market price. It explicitly targets the use case 'what should I bet on today' and distinguishes from sibling tools like 'polymarket_arbitrage' and 'polymarket_edge_tracker' by focusing on edge detection and opportunity discovery without manual pagination.

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

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

The description provides extensive usage context, including when to use it (to discover betting opportunities), how to adjust parameters (knobs like min_liquidity, max_spread_pp), and what to expect from the response (by_segment grouping, diagnostics). However, it does not explicitly state when to avoid this tool in favor of alternatives, such as when specific market data or arbitrage trades are needed, which would improve 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 indicate read-only, idempotent, non-destructive behavior. The description adds critical behavioral details: history bounded by 60-day TTL, decay computed from daily closes, and snapshot gaps. 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 front-loaded with purpose and includes response format and limits, which is helpful. It could be slightly more concise by separating response format, but every sentence adds value.

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

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

Despite no output schema, the description fully explains the return structure (tracked with fields, expired, snapshot_dates) and operational limits (TTL, snapshot gaps). For a complex telemetry tool, this is highly 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 default values (14 days, 1wk), clamping (2-30), and response structure (tracked, expired, snapshot_dates). This goes beyond the schema's basic field 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 provides edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and if it is shrinking. It distinguishes itself from siblings like polymarket_edges (current edges) and polymarket_arbitrage, 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 implies usage context by contrasting fresh vs. old edges, suggesting traders check persistence before acting. It does not explicitly list when not to use or alternative tools, but the context is clear enough for an AI to infer appropriate scenarios.

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 readOnlyHint and idempotentHint annotations, the description details the tool's behavior: it walks the order-book ladder, returns specific fields like top_of_book, vwap_fill_price, slippage, and a verdict. For basket mode, it explains theoretical vs realizable sums, capture ratio, profit, thin legs, and forced directional risk. No annotation contradictions; annotations align.

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

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

The description is well-structured with clear sections (SINGLE-MARKET, BASKET) and bold keywords, but it is quite lengthy (over 200 words). It front-loads the purpose and uses imperative sentences. Could be slightly more concise while retaining all critical 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 complexity (two modes, many return fields) and no output schema, the description provides a complete picture: it lists all returned fields for both modes, explains the context of usage (warning about partial fills), and covers edge cases like thin legs and forced directional risk. No gaps remain.

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

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

The description adds significant meaning beyond the schema: it explains the two modes (single-market vs basket) and which parameter is required for each, clarifies default values, and interprets size_usd differently per mode. It also explains the auto-default logic for side in basket mode. Schema coverage is 100%, but description enhances understanding.

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

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

The description clearly defines the tool as a realizable-vs-theoretical edge check against live order-book depth, explaining both single-market and basket modes. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by stating it should be used before acting on their signals, establishing a clear role.

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 this tool: before any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or polymarket_edges trade above ~$500. It also explains the risk of partial fills converting arbs into unhedged directional positions, providing clear context for when it is essential.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds rich behavioral context: it details compatibility warnings, temporal alignment, skipped cross-type/subtype counters, and explains when spreads are meaningless (e.g., non-equivalent bet shapes or temporal mismatch). No contradiction with annotations.

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

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

The description is dense and well-structured with sections for modes, response, and safety fields. It front-loads the core purpose. However, it is slightly verbose; some sentences could be merged 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 lacking an output schema, the description comprehensively explains the response structure (leg-by-leg prices, matched spreads, compatibility warnings, temporal alignment, counters). This gives the agent complete understanding of what the tool returns and how to interpret edge cases.

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?

All three parameters are documented in the input schema with descriptions. The description adds value by explaining the topic list and the override behavior for explicit parameters. Schema coverage is 100%, and the description deepens understanding.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison for the same resolving question. The two modes (topic shortcuts and explicit tickers) are well-defined.

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 topic mode for pre-mapped macros versus explicit mode for custom pairings. It also warns that real spreads are rare and most pre-mapped topics return compatibility warnings, guiding the agent when not to expect tradeable spreads.

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?

Description adds scoping detail (by identifier) and list-all behavior. Annotations already cover read-only and idempotent, so description adds value 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, front-loaded with primary action. Every sentence is purposeful 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?

For a simple one-parameter tool with comprehensive annotations, the description fully covers purpose, usage, scoping, and pairing with related tools.

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

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

Schema already fully describes the key parameter and its omit behavior. Description restates this, adding no new semantic depth beyond the schema.

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

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

Description clearly states it retrieves a saved value via remember or lists all keys. Verb+resource is specific, and it distinguishes from tools like remember and forget.

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

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

Explicitly says when to use (look up context without re-deriving) and behavior when omitting key. Lacks explicit 'when not to use' but context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so description adds value by detailing return fields (source, citation_uri, raw payload) and the mark_read side effect. 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 concise sentences with no fluff. Front-loaded with the primary purpose, followed by return details and filtering options. Every sentence adds value.

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

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

With no output schema, the description explains return structure and parameter usage sufficiently. Covers filtering, mark_read, polling, and alternative endpoint. Adequate for a read-only tool with optional parameters.

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

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

Schema coverage is 100% with parameter descriptions already present. The description adds contextual examples (e.g., 'sec_8k' for type, ISO timestamp for since) and explains mark_read usage, enhancing understanding beyond the schema.

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

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

Description clearly states 'Pull fired events from your subscription feed', specifying a clear verb and resource. It distinguishes from sibling tools like list_subscriptions which list subscriptions, not events.

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 context on filtering (type, since), mark_read behavior, and mentions an alternative endpoint for scripts/dashboards. Does not explicitly state when not to use, but the guidance is clear and practical.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description goes beyond by detailing the multi-source fan-out, the specific fallback mechanism from GDELT to GNews when rate-limited or 5xx, and the USPTO soft-fail due to API sunset. It also describes the output structure (grouped changes, total count, citation URIs). No contradictions with annotations.

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

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

The description is a single paragraph but well-structured: it leads with example queries, then explains the tool's function, parameter usage, sources, and concludes with the alternative tool. It is dense with information but not unnecessarily verbose. Every sentence adds value, though bullet points could improve readability.

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 sources, fallback logic, soft-fails, and no output schema), the description covers all critical aspects: parameter formats, source behavior, output summary, and alternative tool. No gaps are apparent for callers to understand what the tool does and what to expect.

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

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

Schema coverage is 100%, so baseline is 3. The description adds some context (e.g., 'Use "30d" or "1m" for typical monitoring') and explains accepted formats for 'since', but the schema already provides clear descriptions for all three parameters. The extra context is helpful but not essential beyond what the schema offers.

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 concrete example queries ('What's new with X', 'latest on Y'), then states it provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It lists the exact data sources (SEC EDGAR, GDELT->GNews fallback, USPTO) and explicitly distinguishes from sibling tool 'entity_profile', which provides static profiles. This makes the purpose highly specific and distinguishable.

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

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

The description provides explicit usage context by listing example user queries. It clearly states when to use this tool (for temporal changes) and directs users to an alternative ('Use entity_profile instead when you want the static profile'). It also explains fallback behavior (GDELT->GNews) and soft-fail for USPTO, helping the agent decide when to invoke.

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

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

Beyond annotations, the description reveals scoping by identifier, persistence differences between authenticated and anonymous sessions (24 hours), and that it's a key-value store, all useful behavioral traits.

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

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

Four sentences, front-loaded with purpose and usage, each sentence adds essential information without redundancy. Very 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 key-value store with no output schema, the description covers purpose, usage, behavior, and parameters completely. 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 coverage is 100% so baseline is 3. Description adds value by explaining the key-value pair concept and providing concrete examples (e.g., 'subject_property', 'target_ticker'), which enhances understanding beyond schema.

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

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

The description clearly states the verb 'Save' and resource 'data', and distinguishes from sibling tools recall and forget by specifying the action of storing for later reuse.

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

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

Explicit guidance on when to use ('when you discover something worth carrying forward') and pairs with recall/forget for retrieval and deletion, providing clear context.

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

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

Annotations already mark the tool as readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context by stating that each call cascades through several lookup endpoints internally, replacing 2-3 manual lookups, which informs the agent about performance and internal behavior. 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 relatable example queries that immediately convey purpose. It is well-structured with a clear use case, then a breakdown of supported types with details. While slightly verbose, every sentence earns its place given the complexity of two entity types.

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 explain return values. It does this thoroughly: for 'company' returns ticker, CIK, company name, and citation URI; for 'drug' returns RxCUI, ingredient, brand, and citation URI. It also covers auto-disambiguation and input format acceptance. The tool has moderate complexity with two types, and the description is fully adequate.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant meaning beyond the schema by providing examples for the 'value' parameter (e.g., 'AAPL', 'ozempic') and explaining that the tool auto-disambiguates input (e.g., accepting ticker, CIK, or company name). This helps the agent understand valid inputs and behavior.

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

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

The description starts with user-facing example queries like 'What's the ticker for…' and clearly states the core purpose: resolve a user-spoken name to a canonical identifier. It explicitly positions itself as the first tool to use when you have a name but need an ID, distinguishing it from sibling tools like 'cusip_to_isin' or 'validate_cusip' that operate on existing IDs.

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 ('Use FIRST whenever you have a name but need an ID') and lists supported entity types with input formats. However, it does not explicitly state when not to use it (e.g., if the ID is already known), leaving some ambiguity.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density per entity. No contradictions; adds useful behavioral context.

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

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

Three sentences: first states main purpose, second explains how it works, third gives use case. No fluff, front-loaded.

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

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

Given annotations and full parameter schema, description is complete: explains composite action, output format, and use case. No output schema but description covers what is returned.

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 nuance: first entity is treated as 'subject' for narrative, context disambiguates common names. Adds value 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?

Description clearly states it compares AI visibility across multiple entities, ranks them, and surfaces which is most/least recognized. Distinguishes from ai_visibility_check (single entity) by being a comparative wrapper. Specific verb 'compare' and resource 'AI presence'.

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

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

Explicit use case provided: 'competitive AI-marketing audits' and a concrete question. Implicitly tells not to use for single-entity check (use ai_visibility_check). Lacks explicit when-not or alternatives mention, 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?

The description adds significant behavioral context beyond the annotations: it explains the composite nature (fans out across two services), mentions partial failures (bundlephobia timeout leads to sources_failed), and notes performance characteristics (bundlephobia first measurement can take 5-30s). 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 front-loaded with the core purpose and usage guidance. It is comprehensive but slightly long due to enumerating return fields and alternative ecosystems. However, every sentence adds value, and the structure is logical.

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

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

Despite lacking an output schema, the description details the return fields (summary block, per-advisory detail, links, recent versions) and explains edge cases like partial failures and performance delays. It is fully complete for a tool with two parameters and no output schema.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description confirms that 'package' accepts scoped names and 'version' defaults to latest, but this largely repeats the schema. It does not add substantial new meaning beyond the schema, so a 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 that this tool performs a composite 'should I add this npm package' check, listing specific sources (deps.dev and bundlephobia) and checks performed (license, advisories, version history, bundle size, ESM support). It also distinguishes from other tools by specifying that it is for NPM only in v1.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', guiding the agent away from this tool for non-NPM packages.

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 non-destructive behavior. The description adds significant detail: embedding model (BGE-base-en), chunking (500-char overlapping windows), character cap (200K with truncation flagging), and that passages include offsets for verification.

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 moderately long but every sentence provides unique value. It is front-loaded with the main action and progressively adds details. Could be slightly more concise but remains 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 no output schema, the description explains return format (top-N passages with offsets and scores), behavior (truncation, flagging), and pairing guidance. It covers all necessary aspects for an agent to use the tool effectively.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema: 'limit' gets a range (1-20) and default (5), 'query' gets examples. It doesn't fully compensate for missing schema but adds useful specifics.

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 'Semantic search INSIDE a fetched record,' specifying verb and resource. It differentiates from siblings by mentioning pairing with 'ask_pipeworx_grounded' and implies a distinct use case from other search tools.

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

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

It explicitly says 'Use when the record is too big to cram into the prompt' and notes pairing with 'ask_pipeworx_grounded'. While it doesn't list when not to use, the guidance is clear and provides context for 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 indicate the tool is not readonly, not destructive, and idempotent. The description adds behavioral context beyond annotations: it explains the need for OAuth, the always-on feed requirement, optional delivery channels with specific constraints (SMS cap, webhook auto-disable after 10 failures), and the one-time return of webhook secret. 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 front-loaded with the main action and returns value, then provides details in a structured paragraph. It includes bullet-like lists for types and delivery channels, making it scannable. However, some technical details (e.g., webhook HMAC) add length, but they are necessary for correct usage. Could be slightly more concise but overall 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?

Given the tool's complexity (multiple types, nested params, optional delivery with constraints) and no output schema, the description covers all key aspects: type options, param structures, delivery channels, authentication, and constraints. The return value is mentioned but not detailed (e.g., full response format). This is acceptable for a creation tool but could be slightly more thorough.

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 covers all parameters with descriptions (100% coverage). The description significantly enhances meaning by providing concrete examples for each type (e.g., sec_8k with items codes, polymarket_edge with topic), detailing delivery options (email, SMS, webhook) with validation rules, and explaining the webhook signing process. This goes well beyond the schema's brief 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 verb 'Create' and the resource 'proactive monitoring subscription to a live-data event stream', and specifies that it returns the new subscription ID. It distinguishes from sibling tools by focusing on subscription creation, while siblings like list_subscriptions and unsubscribe handle other lifecycle actions.

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

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

The description mentions the prerequisite of a Pipeworx OAuth account and notes that anonymous/BYO users cannot persist subscriptions. It also describes delivery channels and constraints like SMS cap. However, it does not explicitly contrast with sibling tools that might offer one-time data access (e.g., polymarket_edges) or other ways to get alerts, leaving some ambiguity about when to use this vs. alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context (onboarding entry point, returns categorized examples, optional topic focus) without contradicting annotations.

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

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

The description is front-loaded with purpose but includes a lengthy list of categories and meta-tool names. While comprehensive, it could be slightly more concise without losing meaning.

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

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

Without an output schema, the description fully explains the return format (category-bucketed examples with tool+argument shape) and mentions the tool catalog size. It covers all necessary context for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100% for the single optional 'topic' parameter. The description adds explicit enum values (finance, pharma, etc.) and explains the default behavior (full spread if omitted), going beyond the schema.

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

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

The description clearly states the tool returns category-bucketed example questions for onboarding users who don't know Pipeworx's capabilities. It distinguishes it from sibling tools like ask_pipeworx and deep_research by specifying its role as the first step to explore what is worth asking.

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

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

Explicitly advises using this tool 'FIRST when you do not yet know what Pipeworx can do for you' and to learn about meta-tools. It does not list when not to use it or compare explicitly to all alternatives, but the context is clear and 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?

Beyond the annotations (which indicate non-destructive, idempotent, open-world), the description explains the behavioral nuance: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This adds significant value.

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

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

The description is two sentences long, front-loaded with the primary purpose, and 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?

With a single parameter fully covered by schema and no output schema, the description adequately covers the tool's behavior, side effects, and relation to sibling tools like 'recent_alerts'. It is complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents the 'id' parameter. The description does not add further meaning beyond what the schema provides, resulting in a baseline score of 3.

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

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

The description clearly states 'Cancel a subscription by id.' It uses a specific verb (cancel) and resource (subscription by id). The sibling tools include 'subscribe' and 'list_subscriptions', making the distinction obvious.

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

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

The description explicitly mentions ownership enforcement: 'you can only cancel your own subscriptions.' However, it does not provide explicit when-to-use vs. alternatives or when not to use, though the context makes it clear.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the description adds value by explaining the output format (verdict, structured form, citation, percent delta) and the performance benefit (replaces 4-6 sequential calls). 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 a single, well-structured paragraph that front-loads the purpose with common user queries, then defines usage, scope, and output. Every sentence adds value without redundancy, making it highly concise 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?

Given the tool's simplicity (single parameter, no output schema), the description covers purpose, usage, scope, and return values. It could mention handling of out-of-scope claims or error cases, but overall it is sufficiently complete for an AI agent to use 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% and includes examples like 'Apple's FY2024 revenue was $400 billion'. The description adds further context by clarifying that the claim is a natural-language statement and specifying supported types (company-financial). This goes beyond the schema, justifying a 4.

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

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

The description clearly states the tool's function: natural-language claim verification against authoritative sources, with explicit examples of user intents ('fact check', 'verify the claim that...'). It distinguishes itself from siblings by specifying it supports company-financial claims via SEC EDGAR + XBRL, making the purpose very specific and clear.

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

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

The description provides clear guidance on when to use the tool: 'whenever the agent needs to check whether something a user said is factually correct.' It also defines limitations by stating 'v1 supports company-financial claims (revenue, net income, cash position for public US companies).' While it does not explicitly list alternatives or when not to use it, the scope is well-defined.

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, covering safety and idempotency. The description adds value by specifying that the tool checks structure and the check digit, providing behavioral context beyond annotations.

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

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

The description is a single sentence, no redundant information, and directly addresses the tool's purpose. It is efficiently front-loaded and 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?

For a simple validation tool with one parameter and no output schema, the description covers the core purpose and behavior adequately. It does not describe return value type, but this is acceptable given the lack of output schema.

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

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

Parameter 'cusip' has 100% schema description coverage, and the description merely reiterates the format and example given in the schema. No additional semantic meaning is added beyond what the input schema provides.

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

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

The description clearly states the tool validates a CUSIP, specifies the format (9-character US/Canada securities identifier), and explains what it checks (structure + check digit). This provides a specific verb-resource pair and distinguishes it from sibling tools like validate_isin.

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

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

The description implies usage for validating a CUSIP but does not explicitly state when to use it versus alternatives like validate_isin, nor does it provide guidance on when not to use it. The context of sibling tools helps, but the description itself lacks direct usage guidance.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds 'Keyless/offline' and limitation about issuer resolution. No contradictions.

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

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

Two sentences, no wasted words. Front-loaded with definition and example, then details. 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?

Covers input format, validation logic, return values, and key properties. Could mention error handling (e.g., invalid ISIN response). Otherwise complete for a simple validation tool.

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

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

Schema covers parameter with example. Description adds context on format (ISO 6166, 12 chars), check digit, and return content. Adds value beyond schema.

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

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

Clearly states it validates an ISIN by checking structure and check digit, returns country prefix and NSIN. Distinguishes from siblings like validate_cusip and cusip_to_isin by specifying the security type and behavior.

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

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

Implies usage for validating ISIN strings without resolution. Mentions 'does NOT resolve the issuer', hinting at alternatives. Could explicitly state when to use this vs validate_cusip or cusip_to_isin.

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