Isin

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

Annotations already cover readOnly/openWorld/idempotent safety. The description adds valuable context: default model behavior, BYO-key payment note, and per-model return structure. It doesn't mention rate limits or error cases, but the annotation coverage lowers the burden.

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

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

Three sentences, each earning its place: purpose, configuration, and output/use cases. Front-loaded with the main action, no repetition or 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?

No output schema, so the description appropriately explains the return shape (per-model score/confidence/signals/raw_response + combined view). It also covers model selection and use cases. Lacks detail on signals content or failure modes, but for a read-only probe tool it's 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 meaning beyond the schema by explaining the default model when 'models' is omitted, the payment responsibility for '_apiKey', and the disambiguating role of 'context'.

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

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

The description uses a specific verb ('probe'), names the resource ('LLMs'), and defines the output (visibility score 0-100 per model). It clearly distinguishes from siblings like scan_competitor_ai_presence by focusing on per-model scoring and visibility.

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

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

Explicitly states use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to pass _apiKey. It doesn't mention alternative tools or exclusions, so it stops short of a 5.

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

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

With annotations already declaring readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, the description adds valuable behavioral context: it routes to the right tool, fills arguments, returns structured answers with stable citation URIs, works on every tier, and requires only one fast call. This goes beyond the annotations by explaining what the agent can expect in terms of functionality 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?

The description is front-loaded with the critical instruction ('PREFER OVER WEB SEARCH'), then provides domain coverage, tool behavior, usage triggers, examples, and escalation paths. Every sentence contributes meaningful information; the length is justified by the tool's nature as a broad entry point. No filler or redundancy.

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

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

Despite having no output schema, the description explains the output format (structured answer with pipeworx:// citation URIs), the tool's internal routing behavior, and when to escalate to more specialized tools. It covers domains, example queries, and functional guarantees. This is complete for a meta-query 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%: all six parameters are aliases for the 'question' field, and the schema already provides descriptions for each. The description's examples reinforce the parameter's role but do not add additional semantic meaning beyond what the schema covers. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: it routes factual questions to 5,529 tools across 1,455 sources and returns structured answers with citation URIs. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives for different needs, making its role as the default entry point 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?

Usage guidance is explicit and actionable: 'START HERE for most questions' and 'PREFER OVER WEB SEARCH' clearly indicate when to use. It also provides alternatives with specific triggers ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'), and includes concrete example questions to illustrate ideal usage.

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

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

Annotations already mark it read-only, idempotent, and non-destructive. The description adds valuable context: experimental routing candidates may be enabled, currently none are active so it matches ask_pipeworx exactly, and results feed merge decisions. It also clarifies it is a full working router, not a fallback stub.

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 sized and well-structured. Each sentence adds distinct information: what it is, current state, usage, and reassurance. Slightly verbose but not wasteful.

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

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

The tool has a simple schema (one question param with aliases) and no output schema. The description covers the experimental nature, current state, usage context, and comparison behavior. It references 'same response shape' but does not detail the response, which is a minor gap.

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

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

Schema coverage is 100% with all aliases documented. The description mentions 'same arguments as ask_pipeworx' but adds no new parameter-specific meaning. It does reinforce that the question parameter works identically to the stable version, which is helpful but not extra detail.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It explicitly distinguishes itself from the stable ask_pipeworx sibling and states its experimental nature.

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 states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It implies the alternative is the stable router and mentions comparison against it. However, it doesn't explicitly name ask_pipeworx as an alternative, though siblings make it obvious.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds substantial detail beyond annotations: the refusal mechanism with specific refusal reasons, the exact output structure including evidence and confidence, and the guarantee to use only tool result content. 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, then systematically covers mechanism, output, refusal reasons, use cases, and cost. Every sentence adds value and the structure is logical, despite the length being above average.

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

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

For a tool with moderate complexity and no output schema, the description is complete: it details the return format, refusal behavior, use cases, and relationship to ask_pipeworx. The annotations cover safety and world-knowledge aspects, and the description fills all remaining gaps.

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

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

Schema description coverage is 100% — all parameters are aliases for 'question' with descriptions. The description does not add parameter-level details, but the schema fully documents them, so baseline 3 is appropriate.

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

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

The description clearly states the tool is a grounded, hallucination-resistant answer mode for high-stakes reads. It differentiates from sibling ask_pipeworx by explaining the evidence extraction and refusal behavior, with a specific verb ('answer') and resource (Pipeworx).

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

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

Explicit guidance is provided: use when answers will be quoted/cited/acted on, and prefer ask_pipeworx for casual lookups. The cost tradeoff (one extra LLM call) is also stated, giving clear when-to-use and when-to-avoid 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?

The description extensively discloses behavior beyond annotations: resolver contract (market_match_confidence, match_score), fan-out logic with specific data sources, response shapes, safety short-circuits (low_confidence_match, market_closed_or_inactive), wide-spread handling, and resolution-rule risk parsing. It even includes caveats about truncated data and 429 fallbacks. Annotations are additive (readOnlyHint, idempotentHint) and not contradicted.

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-organized with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK). Every sentence adds operational detail, and the examples are concrete. It is not concise in length, but the structure makes it easy to scan and the density is justified for a complex tool.

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

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

Given the tool's complexity and the lack of an output schema, the description comprehensively covers return shapes (result.market, result.analysis, result.evidence), resolver contract, parent-event extraction, news fallback behavior, safety short-circuits, and resolution-rule risk. It leaves little ambiguity for an agent to select, invoke, and interpret results correctly.

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

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

Schema already covers all three parameters with 100% coverage, so baseline is 3. The description enriches the 'market' parameter by explaining it accepts slug, URL, or question text—which is in the schema—but also provides resolution and classification behavior that gives deeper meaning to how the parameter is interpreted. It does not add new semantic details for 'depth' or 'include_raw' beyond the schema, but the overall context boosts utility.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from siblings like polymarket_arbitrage and polymarket_edges by focusing on data-packed research for a single market, with classification and fan-out 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?

The description explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear context for when to invoke. It doesn't explicitly name alternative tools or when-not-to-use, but the usage 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?

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses concrete behavioral details: data sources (SEC EDGAR/XBRL, FAERS, FDA), handling of off-calendar fiscal years, result sorting by primary metric, and return format (paired data + citation URIs). No contradiction with annotations.

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

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

The description is front-loaded with trigger phrases and is dense with useful information. It is somewhat lengthy (~150 words) but every sentence contributes value, and the structure flows logically. Could be tightened slightly, but remains highly 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?

With no output schema, the description covers return format (paired data + citation URIs), data sources, sorting behavior, and entity count limits. It addresses edge cases (off-calendar fiscal years) and handles both modes (company and drug) thoroughly, making it 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?

While schema covers basic param definitions, the description adds significant meaning: type='company' pulls specific financials (10-K revenue, net income, cash, long-term debt) and type='drug' pulls adverse-event/trial counts. It also clarifies value formats (tickers/CIKs vs drug names), going well beyond the schema's brief examples.

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: side-by-side comparison of 2–5 companies or drugs in one call. It uses specific trigger phrases (e.g., 'X vs Y', 'which is bigger') and distinguishes from sequential single-pack lookups, separating it from siblings like entity_profile.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides trigger phrases. It gives clear when-to-use context and implicitly excludes single-entity lookups. It also mentions it replaces 8–15 sequential lookups, reinforcing the use case.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context: the default country code 'US', the fact that the check digit is computed, and an example of the transformation. No contradiction with annotations.

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

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

The description is a single sentence followed by a helpful example, front-loading the verb and resource. Every word earns its place 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, deterministic conversion tool, the description is complete. It explains the input, the transformation, and provides an example output, matching the schema and annotations. No output schema exists, but the example fills that gap.

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

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

Schema coverage is 100% with descriptions for both parameters. The description enhances this by explaining the algorithm (prefix + check digit) and including a worked example, adding value beyond the schema's purely descriptive fields.

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 action: 'Convert a CUSIP to its ISIN', with a specific method (prefixing country code and appending check digit) and a concrete example. This distinguishes it from sibling validation tools like validate_cusip or 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 when a CUSIP needs conversion to an ISIN, but does not explicitly mention when to use this over sibling tools like validate_cusip or validate_isin. No exclusions or alternative guidance is provided.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), it discloses the internal decomposition into facets, parallel routing, return packet contents (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field), semantic excerpting, and expected latency (15-60s, thorough up to 90s). 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?

Although long, every sentence contributes unique operational information—prerequisites, use cases, behavioral details, return format, timing. Information is front-loaded with the account requirement and organized in a logical flow.

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

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

No output schema is provided, but the description compensates by fully specifying the findings packet, citation mechanics, contradictions[] behavior, gap recovery, and latency. It also covers when not to use the tool, making it 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 description expands on both parameters: it explains that depth values correspond to facet counts and hop behavior ('quick=3... standard=5... thorough=8 paid'), and clarifies that the question should be natural language and broad/multi-part is fine. This goes beyond the schema's generic 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 states 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call' and explicitly distinguishes itself from ask_pipeworx and open-web search, making its purpose and scope unmistakable.

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

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

It explicitly says 'Best for broad/multi-part questions over structured data', directs single lookups to ask_pipeworx, and warns against using it for breaking news. It also notes account sign-in requirements and the fallback to ask_pipeworx when not signed in.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value beyond these: it discloses that the tool returns top-N most relevant tools with full input schemas and curated examples, and that results are ready to call directly without a second lookup. This contextual behavior (returning multiple candidates, ready-to-call) is not implied by annotations, so a 4 is appropriate.

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 slightly long due to a comprehensive domain list, but every sentence contributes: purpose, usage context, return format, and when to call first. The structure is logical and front-loaded with the core purpose. It earns its length without being redundant.

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

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

For a discovery tool with 6 parameters (1 required), no output schema, and strong annotations, the description is complete. It tells the agent what it returns (names, descriptions, schemas, examples), how results are formatted (ready to call directly), and when to prioritize it ('Call this FIRST'). No critical information is missing.

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

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

Schema description coverage is 100%, with all six parameters documented, including aliases and an example. The description's mention of 'top-N' aligns with the limit parameter but adds no new semantics beyond the schema. Since the schema carries the full burden, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the resource (tools) and the action (find/discover), and the domain list distinguishes it from sibling domain-specific tools. It is a meta-tool for discovery, clearly differentiated from tools like polymarket_edges or pipeworx_trending.

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

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

Explicit guidance is given: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly defines when to use the tool and implies the alternative (directly calling a known tool) when a single answer is desired.

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 reveals significant behavioral details beyond the annotations: parallel fan-out across multiple sources, up to 5 filings, LATEST 10-K fundamentals sorted by period, patent API sunset with soft-fail, and GDELT→GNews fallback. These details are valuable and non-obvious.

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 information-dense, front-loaded with example user intents and a clear recommendation. Some repetition of schema constraints exists, but every sentence contributes useful context or examples.

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 and two required parameters, the description fully covers inputs, outputs, source details, limits, fallbacks, and failure behavior. It also names the prerequisite tool (resolve_entity) and explains the single-call benefit, making it very 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 already documents both parameters with 100% coverage, so baseline is 3. The description adds concrete examples (AAPL, 0000320193), clarifies zero-padding requirement, and reinforces that names are unsupported—providing value beyond the schema.

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

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

The description clearly states the tool creates a full cross-source profile of a US public company, listing concrete outputs like filings, fundamentals, patents, news, and LEI. It distinguishes itself from chaining single-pack SEC/XBRL/news lookups, though it doesn't explicitly differentiate from sibling tools like compare_entities.

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

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

Provides explicit when-to-use guidance: prefer this over chaining single-pack lookups for holistic views. Also gives clear exclusions: names are not supported, use resolve_entity first, and only ticker or zero-padded CIK are accepted.

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 destructiveHint=true and idempotentHint=true, which covers the safety profile. The description adds context about deleting agent-saved memories and clearing sensitive data, but does not disclose additional side effects beyond the annotated destructive behavior.

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

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

Three concise sentences, each serving a purpose: definition, usage scenarios, and related tool pairing. No redundant or filler content.

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

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

For a simple tool with one required parameter and no output schema, the description covers what, when, and related tools. The idempotent and destructive annotations complete the behavioral context, making the tool fully understood.

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 fully documents the single 'key' parameter with a clear description, achieving 100% coverage. The tool description reinforces 'by key' but adds no additional parameter semantics beyond what the schema already provides.

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

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

Description uses the specific verb 'Delete' and identifies the resource as 'a previously stored memory by key', clearly distinguishing it from siblings like remember and recall. It precisely states the tool's function.

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 scenarios: stale context, task completion, or clearing sensitive data. It also mentions pairing with remember and recall, offering related tool context, though it lacks formal exclusions.

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

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

Annotations already mark the tool as readOnly, openWorld, and idempotent. The description adds valuable context about the internal process ('Fetches the page, extracts title/description/key links') and the output format ('single text blob ready to drop at site-root/llms.txt'). This goes beyond what annotations provide, though it omits potential edge-case behavior like error handling.

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 focused sentences. The first sentence states the core action, the second explains the process and output, and the third lists relevant use cases. Every sentence earns its place with no redundancy or 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?

For a tool with only two parameters, no output schema, and existing annotations, the description covers the essential aspects: what it does, how it works, what it returns, and when to use it. The output format is explicitly described, making the tool self-contained.

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 descriptions for both 'url' and 'max_links'. The description adds no additional parameter-specific details beyond what the schema states, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL'. It clearly distinguishes this tool from siblings like scan_competitor_ai_presence by focusing on file generation, and the use cases further reinforce its unique 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 provides clear use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' However, it does not explicitly name alternative tools or state when NOT to use this tool, stopping short of full alternative guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable context: returns specific fields, lists only active subscriptions by default, and is scoped to the caller. This exceeds what annotations provide 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 concise sentences, front-loaded with the purpose, followed by return fields and usage guidance. Every sentence earns its place with zero filler.

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

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

The tool is simple (one optional param, no output schema). The description covers purpose, use case, returned fields, and active/inactive behavior, making it fully complete for an agent to decide when and how to invoke it.

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

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

The schema has 100% coverage with one self-explanatory parameter include_inactive. The description does not explicitly elaborate on the parameter but implies its meaning by contrasting active vs cancelled subscriptions. Baseline 3 is appropriate when schema handles parameter documentation.

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 with a specific verb and resource: 'List the caller's active subscriptions.' It further distinguishes from sibling tools like subscribe and unsubscribe by mentioning 'before adding more' and 'to find an id to cancel.'

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 usage guidance is provided: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent exactly when to use this tool relative to subscribe/unsubscribe.

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 are neutral (all false), so the description carries the behavioral disclosure burden. It thoroughly covers rate limiting (5/day), cost (free, no quota), return behavior (claim_token without account), and operational context (daily digests, roadmap impact). No contradiction with annotations observed.

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

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

The description is long but every sentence adds critical guidance: purpose, use cases, exclusions, token usage, rate limit, and cost. It is front-loaded with the core purpose. While it could be broken into bullets, it remains efficient and not redundant.

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 and uninformative annotations, the description fully compensates. It explains expected responses (claim_token), usage workflow, limitations, and what qualifies as valid feedback. An agent has all necessary context to invoke this tool correctly and understand consequences.

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?

Input schema covers 100% of parameters with descriptions, establishing a baseline of 3. The description adds value by explaining claim_token's read-back purpose, how to avoid pasting end-user prompts, and the intended content of 'context' (tool/pack/vertical). This enriches parameter understanding beyond the schema's literal definitions.

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

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

The description starts with 'Tell the Pipeworx team something is broken, missing, or needs to exist' – a specific verb and resource that clearly distinguishes it from all sibling tools, none of which are feedback-related. The purpose is unmistakable and aligns with the tool name and title.

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 scenarios (bug, feature/data_gap, praise), a clear exclusion ('ONLY for tools served by this Pipeworx connection'), and an alternative action (file with the other MCP server). It also explains how to identify Pipeworx tools, leaving no ambiguity about appropriate invocation.

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?

Even with readOnlyHint=true and destructiveHint=false, the description adds significant behavioral context: it discloses self-aggregation, derivation from CF analytics-engine, no PII, and caching windows (5min-1h). This goes well beyond what annotations provide, giving the agent a clear model of what the tool does and its side effects (none).

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: a core statement, a bulleted 'Useful for' section, and a concise data/caching note. It is slightly longer than necessary, but every sentence adds value and the most important information is front-loaded.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is complete. It covers what is returned (top tools, top packs, total call volume), the data format ('just (pack, tool, count)'), privacy (no PII), caching, and usage context. No gaps for an agent to invoke it correctly.

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

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

The single parameter 'window' is fully documented in the schema with enum values and a meaningful description ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The tool description only mentions the window in passing ('24h, 7d, or 30d') and adds no new parameter semantics, so the baseline of 3 applies given high schema coverage.

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

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

The description explicitly states the function: 'Returns the top tools, top packs, and total call volume over a recent window', with a clear verb and resource. It also distinguishes itself from siblings by framing the data as a self-aggregating signal from other AI agents, not just a generic discovery tool.

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

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

Provides a clear 'Useful for' list with three specific scenarios (discovering hot data sources, confirming canonical tools, aligning use cases) which gives explicit context for when to use it. However, it does not mention when not to use it or explicitly name alternative tools, so it falls short of a 5.

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

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

The description goes well beyond the annotations (readOnly, openWorld, idempotent) by detailing internal algorithms, thresholds (>3pp), placeholder filtering, fill check behavior, and when a signal should not be traded. It also explains the skipped_low_similarity counter and partition filter, providing deep operational transparency.

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

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

The description is long but tightly structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds operational detail; there is no filler or repetition. The front-loaded purpose and immediate mode guidance make it easy to scan.

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

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

Despite having no output schema, the description fully explains the response structure (opportunities[], partition_check fields) and the behavior in edge cases (thin legs, realizable_edge_pp <= 0). It covers all foreseeable usage context, including cross-event patterns and filtering pitfalls, making the tool self-sufficient.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema. It clarifies the exact format of event slugs, provides example values, explains when to prefer event vs topic, and describes what each mode does with the parameter. It also explains the no-args behavior, which is not evident from the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between event and topic modes, and the mention of 'arbitrage' differentiates it from sibling tools like polymarket_edges or polymarket_kalshi_spread.

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 usage guidance is provided: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also directs users to 'polymarket_fill_risk' for custom sizing, naming an alternative tool and clarifying when not to use this one.

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 this as read-only/idempotent, but the description goes far beyond by disclosing caching behavior ('Cached 1h at the KV level keyed on all knobs'), methodology details (lognormal barrier, GDELT ratio, per-sport bias correction), response structure, and important caveats like the Fed signal unreliability. It also warns about 24h price moves and diagnostics for empty segments, giving the agent a full picture of behavior and side effects.

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

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

The description is long and dense, but it is front-loaded with a one-sentence purpose and then logically organized into sections (model families, structural arbitrage, concentrated longshot, knobs, response, diagnostics, caching). Every sentence contributes substantive information, though the sheer volume could overwhelm. Given the tool's complexity, the length is justified, but it is not as succinct as the highest bar.

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?

There is no output schema, so the description carries full responsibility for explaining what the tool returns. It thoroughly describes top-level fields (by_segment, fed_candidates, _diagnostics), the contents of each segment, filter behavior, and potential causes for empty results. It also covers caveats like the Fed note and cache behavior, making it highly complete for an agent to invoke correctly and interpret results.

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

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

Although schema coverage is 100%, the description adds essential operational meaning beyond raw definitions. It explains how slippage_pp interacts with edge calculation and Kelly sizing, why min_kelly doesn't apply to partition overrounds, and how min_partition_leg_kelly filters per-leg Kelly. It also gives concrete recommended values (e.g., max_spread_pp=2, min_liquidity=5000) and contextualizes them with market microstructure facts. This greatly enhances parameter understanding.

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

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

The opening sentence clearly states the tool's function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This is a specific verb+resource combo that distinguishes it from siblings like polymarket_arbitrage or polymarket_edge_tracker by focusing on model-driven, structural, and longshot opportunities. The added 'what should I bet on today' framing further clarifies its intended niche.

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 positions the tool for daily bet discovery ('Built for "what should I bet on today"') and explains when to use knobs like min_liquidity and max_spread_pp to filter for tradeable edges. It does not name alternative sibling tools or state explicit 'when not to use' scenarios, but the use case and behavior are clear enough to guide an agent.

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

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

With annotations declaring read-only and idempotent behavior, the description still adds substantial behavioral transparency: it details the response structure (tracked, expired, snapshot_dates), explains that snapshots are written on cache-miss so gaps mean no scan, and discloses limits like the 60-day TTL and that decay is computed from daily closes, not intraday. This goes far beyond the annotations.

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

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

The description is front-loaded with the purpose and uses clear sections (Args, RESPONSE, LIMITS) to present detailed information efficiently. Every sentence contributes value, covering purpose, parameters, output structure, and limitations without unnecessary 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 no output schema, the description fully compensates by explaining the response fields (tracked, expired, snapshot_dates) and their meanings, along with behavioral caveats like TTL and cache-miss semantics. This makes the tool's behavior and constraints complete for an 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 coverage is 100%, so the baseline is 3. The description adds extra semantics by explaining the 'window' as a snapshot family and clarifying the lookback concept. It also notes that history depth is bounded by the 60-day TTL, which informs how the 'days' parameter behaves in practice. No contradictions with the schema.

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

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

The description clearly states the tool's function: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question (how long an edge has existed and whether it's shrinking) and distinguishes itself from sibling tools by focusing on historical tracking vs. current edges. The example of fresh vs. 3-week-old edges adds clarity.

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

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

The description provides context on when to use the tool by framing the question it answers ('how long has this edge existed and is it shrinking?') and contrasting with the qualitative difference between edge ages. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to infer its use case relative to sibling tools like polymarket_edges.

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

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

Annotations already mark this as read-only, non-destructive, and idempotent, and the description adds significant behavioral context: how size_usd is interpreted differently in each mode, the verdict categories (clean|degraded|cannot_fill), the risk of partial fills becoming unhedged directional positions, and the return fields. No contradiction with annotations.

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

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

The description is lengthy but well-structured, with capitalized mode markers (SINGLE-MARKET, BASKET) and clear enumeration of outputs and risks. It is front-loaded with the core purpose and every sentence carries essential information. Slightly overlong, but justified by the tool's complexity; a trained model can parse it effectively.

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

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

Given the tool's complexity, the absence of an output schema, and the presence of two distinct modes, the description is remarkably complete. It lists return fields for both modes, explains the risk of partial basket fills, and provides thresholds for usage. It gives the agent everything needed to invoke the tool correctly and interpret results.

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

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

Schema coverage is 100%, giving the baseline of 3, but the description goes far beyond the schema. It explains the mutual exclusivity of market and event, the meaning of side in each mode (including auto-detection), and the dual interpretation of size_usd (max spend vs target proceeds vs settlement notional). This substantially enriches parameter understanding.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which is a specific, action-oriented purpose. It clearly distinguishes two modes (single-market and basket) and enumerates the outputs, making the tool's function unambiguous. It also differentiates from siblings by explicitly framing it as a pre-trade risk check for polymarket_arbitrage and polymarket_edges.

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

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

The description gives explicit 'when to use' guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains mode selection (market vs event) and parameter usage, providing clear context without leaving the agent to guess.

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

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

Annotations declare readOnly and idempotent hints, so safety is covered. The description adds detailed behavioral context: how compatibility_warning and temporal_alignment expose non-equivalence, why matched_pairs:0 may mean unrelated events, and what skipped_cross_type/subtype counters mean. This goes well beyond annotations and enhances transparency.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. Every sentence conveys useful information, but it could be tightened without losing meaning, so it scores 4 rather than 5.

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

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

With no output schema, the description carries the burden of explaining return values and edge cases. It details the response fields (leg-by-leg prices, spread[].top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and conditions under which they are meaningful. This is comprehensive for a complex tool.

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

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

The schema already provides descriptions for all three parameters with examples and override behavior. The main description adds that topic auto-fetches matching events and that explicit tickers enable custom pairings, plus the full list of shortcuts is reiterated. This reinforces meaning but largely duplicates schema information, so a 4 is appropriate.

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

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

The description clearly states it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, specifying two input modes and what the response contains. This distinguishes it from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description explains the two usage modes (topic shortcuts vs explicit tickers) and warns that most pre-mapped topics return compatibility_warning today, setting expectations. It does not explicitly name alternative tools for when this one is inappropriate, but it gives clear context for selecting between modes and interpreting results.

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

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

Annotations already cover safety (readOnlyHint=true, destructiveHint=false, idempotentHint=true). The description adds useful behavioral context: scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the list-all behavior when key is omitted.

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 purpose, followed by usage context and scoping/related tools. Every sentence adds value with no redundancy.

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

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

For a simple one-parameter retrieval tool with rich annotations and no output schema, the description covers functionality, usage, scoping, and sibling relationships. It is 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% and the parameter description already explains the omit-to-list behavior. The description adds no new parameter details beyond reinforcing what the schema states, so baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves a value previously saved via remember or lists all saved keys when the key argument is omitted. It distinguishes itself from siblings by explicitly referencing remember and forget as companion 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?

Provides explicit usage scenarios (look up user's target ticker, address, prior research notes) and explains when to use alternatives by pairing with remember for saving and forget for deleting. Also clarifies scoping to the agent's identifier.

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 read-only, idempotent, open-world. Description adds meaningful context: returned events carry source/citation_uri/payload, mark_read side-effect, and the feed is persisted. No contradiction with annotations; the description enriches safety and state-change behavior.

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

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

The description is a single tight paragraph, front-loaded with the core purpose, then specific details. Every sentence delivers value—no fluff or repetition. Appropriate length for 5 optional parameters.

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 5 optional params, no output schema, and comprehensive annotations, the description covers the return payload (source, citation_uri, raw event), filtering logic, and read-state behavior. It is complete for a read-only polling tool.

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

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

Schema covers all 5 params with descriptions, so baseline is 3. The description adds an example filter value ('sec_8k'), clarifies mark_read's effect on the next call, and ties 'since' to 'fired_at', providing semantic nuance 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 it 'Pull fired events from your subscription feed' with specific behaviors (filtering, mark_read), but does not explicitly differentiate from sibling tools like list_subscriptions or subscribe. The resource ('alerts') and verb are specific, yet without sibling comparison it's clear but not top-tier.

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 mentions when to use the tool ('Polls work fine') and points to an alternative REST endpoint for scripts/dashboards. However, it doesn't state when NOT to use the tool or contrast with sibling tools like list_subscriptions, so it's useful context but not explicit exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, but the description adds substantial behavioral context: parallel fan-out to SEC EDGAR, GDELT→GNews fallback (with rate-limit/5xx condition), USPTO PatentsView sunset causing soft-fails, and the return shape (changes[] + total_changes + citation URIs). No contradiction.

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

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

Despite its length, every sentence carries information: query examples, source details, fallback logic, parameter syntax, return format, and an alternative tool. It is front-loaded with example queries and states the core function immediately, with no filler.

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

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

The description covers purpose, usage, data sources, failure modes, parameter syntax, return structure, and alternatives—fully sufficient for a complex multi-source tool with no output schema. Nothing critical is missing.

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

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

Schema coverage is 100% with thorough descriptions for all three parameters (e.g., 'since' already documents ISO/relative formats and typical use). The tool description does not add meaningful parameter semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call,' with specific verbs and resources. It distinguishes itself from sibling entity_profile by contrasting dynamic changes vs static profile, making the purpose unmistakable.

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

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

It gives explicit usage examples ('what's new with X', 'updates on Acme') and provides a direct alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' This is clear when-to-use guidance with an explicit alternative.

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

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

Annotations already cover idempotency and non-destructive behavior. The description adds meaningful behavioral context: key-value pair scoped by identifier, persistence differences between authenticated and anonymous sessions, and cross-session retention. This goes beyond the structured hints, though it could state overwrite semantics.

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

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

Four sentences, purpose-first, with no fluff or redundancy. Each sentence contributes value: what it does, when to use, how it works, and related tools.

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 two-parameter tool, the description covers the operation, usage context, persistence behavior, and sibling tools. No output schema exists, but the tool returns no structured output, so none is needed. The description is complete for effective use.

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

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

Schema coverage is 100% and both parameters have descriptive examples. The description adds contextual scoping ('scoped by your identifier') but no new parameter syntax or format. Baseline 3 is appropriate since the 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 action ('Save data'), the resource (key-value store), and the scope (across conversations/sessions). It distinguishes from sibling tools by naming recall and forget as paired operations.

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

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

Explicit when-to-use guidance is provided with concrete examples (resolved ticker, target address, user preference, research subject). It also points to alternatives ('Pair with recall... forget to delete'), giving clear context for when this 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 declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: internal cascading lookups, graceful degradation when GLEIF/OpenFIGI unavailable, explicit reporting of unresolved identifiers, and the remark that it replaces 2-3 manual lookups. This goes well beyond annotation basics.

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

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

The description is long but front-loaded with example queries and structured by supported types. Every sentence adds functional detail, though a few embellishments could be trimmed without loss. Organization is clear and scannable.

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

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

For a tool with no output schema, the description covers return values for each type, fallback behavior, and unresolved identifier reporting. It stops short of specifying exact output JSON structure, but given the complexity and the presence of rich annotations, it is largely 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% and already explains both parameters, types, and example values. The description adds examples (AAPL, 0000320193, ozempic) and clarifies input formats for each entity type, but this is marginal enrichment beyond the schema.

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

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

The description clearly states the tool resolves user-spoken names to canonical official identifiers, with specific verbs ('resolve') and resource types (company, drug). It distinguishes itself from siblings by positioning it as the prerequisite for tools that require IDs, and enumerates supported identifier types.

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 instructs 'Use FIRST whenever you have a name but need an ID', and provides concrete example queries indicating when to invoke it. It does not explicitly mention when not to use alternatives, but the context is clear that this is the go-to lookup tool for name-to-ID resolution.

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 valuable behavioral detail: it probes each entity via ai_visibility_check, ranks by score, surfaces most/least recognized, and returns a ranked list with score/confidence/signal density. It goes 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?

The description is three sentences, front-loaded with the main action, then process, then use case and output. The example quote adds helpful context without redundancy. Every sentence earns its place.

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

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

No output schema exists, so the description properly explains return values (ranked list with score, confidence, signal density). It covers purpose, process, and use case. It doesn't mention first-entry-subject handling (but schema does) or potential cost/time implications, but for a moderate-complexity tool with rich annotations and 100% schema coverage, it is sufficiently complete.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces that entities are 'your brand + N competitors' but does not add significant meaning beyond the schema's per-parameter descriptions. It doesn't elaborate on the models/_apiKey interplay or context parameter beyond what schema already provides.

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

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

The description uses a specific verb 'Compare' with a clear resource 'AI visibility across multiple entities side-by-side.' It distinguishes from the sibling ai_visibility_check by explicitly describing multi-entity comparison and ranking, while also referencing the underlying probe mechanism. This makes the purpose unmistakable.

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

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

Provides an explicit use case ('competitive AI-marketing audits') with a concrete example query. It implies the single-entity alternative (ai_visibility_check) by saying 'across multiple entities,' but does not explicitly state 'use ai_visibility_check for a single entity' or mention when not to use this tool. Clear context but no formal exclusions.

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

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

Annotations already declare read-only, idempotent, and non-destructive. The description adds noteworthy behavioral details beyond that: partial failures degrade gracefully, bundlephobia's first measurement may take 5-30s, and the `sources_failed` field will list timeouts while the rest of the result still returns. This prepares the agent for latency and partial result handling.

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

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

Every sentence earns its place: purpose, usage, output fields, ecosystem limitation, and failure behavior are each covered in one dense but efficient paragraph. The most important information (what it does) is front-loaded, and there is no redundant or filler content.

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

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

With no output schema, the description takes on the duty of explaining return values. It lists the summary block fields, per-advisory detail, links, and alternative versions. It also covers timeout behavior and partial failure semantics, making the tool's behavior fully predictable for an agent.

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

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

The input schema has 100% description coverage for both parameters: `package` (with scoped package acceptance) and `version` (defaults to latest). The description does not add any new parameter-level semantics, so it gets the baseline score of 3 for a well-documented schema.

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

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

The description uses a specific verb ('check') with a clear resource (an npm package) and immediately distinguishes itself from siblings by describing the composite fan-out across deps.dev and bundlephobia. It targets a common agent question ('should I add this npm package') and names the exact data sources, making it unmistakable.

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

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

Explicit usage triggers are given: 'Use whenever an agent asks "is X safe / popular / small"'. It also provides an exclusion ('NPM ecosystem only in v1') and directs users to an alternative ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), giving clear when-to-use and when-not-to-use guidance.

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

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

Adds rich context beyond annotations: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with 500-char overlapping windows, and enforces a 200K char cap with truncation flagging. This directly informs the agent about output shape and edge-case behavior, complementing the read-only/idempotent hints.

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 compact paragraph with a clear flow: purpose, usage scenario, pairing, and technical behavior. Every sentence earns its place; no filler. It is front-loaded with the core function and structured logically.

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 schema, the description covers all essential aspects: what it does, when to use, how it behaves (truncation, output format), and how it integrates with ask_pipeworx_grounded. No significant gaps remain for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by elaborating on the text parameter with real-world examples and framing 'top-N' as the limit parameter, plus explaining the offset feature. It slightly exceeds what the schema provides, but the limit param is not deeply enriched, so a 4 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 states a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes from siblings by emphasizing searching within already-fetched text, contrasting with other tools like ask_pipeworx_grounded. Examples (SEC 10-K, article) further anchor the purpose.

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

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

Explicitly describes when to use: 'Use when the record is too big to cram into the prompt.' It names the alternative ask_pipeworx_grounded and explains the pairing pattern, giving clear guidance on when this tool is preferred and how it fits in a workflow.

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=false and idempotentHint=true, but the description adds critical behavioral details: OAuth requirement, subscription-id return, SMS verification and 10/day cap, and webhook auto-disable after consecutive failures (in delivery schema description). These exceed the annotations and accurately describe side effects without contradiction.

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

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

The main description is dense but well-organized: purpose, return, auth prerequisite, supported types, delivery channels. Each sentence carries useful information and no filler. The schema's delivery description is also thorough, though slightly long. Overall, efficient and structured.

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

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

For a tool with nested objects, enums, and no output schema, the description is remarkably complete: it covers required auth, return value, type-specific parameter patterns, delivery options and their constraints (including webhook signature handling in the schema). The only minor gap is that webhook is not mentioned in the main description, but it is fully covered in the schema, which the agent will see.

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

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

Schema coverage is 100%, but the description enriches semantics with concrete examples per type (e.g., items:['5.02'] = officer change, topic:'fed', series_id:'UNRATE') and clarifies the 'feed always on' behavior for delivery. This adds value beyond the baseline structured 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 opens with 'Create a proactive monitoring subscription to a live-data event stream' — a specific verb and resource. It also states the return value ('Returns the new subscription id'), clearly distinguishing this creation tool from siblings like list_subscriptions 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 clear context for use: requires a Pipeworx OAuth account, distinguishes delivery channels (always-on feed vs optional email/sms), and implicitly contrasts with recent_alerts by noting the feed can be pulled via that tool. It lacks explicit when/when-not statements but gives sufficient conditions and prerequisites.

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 the safety profile. The description adds behavioral context beyond annotations by detailing the return format (category-bucketed example questions with exact tool + argument shape), the optional topic focus, and its purpose as the entry point from a live catalog. This is useful and does not contradict any annotations.

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

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

The description is somewhat long but every sentence carries useful information: natural-language query examples, purpose, return format, invocation options, and when-to-use guidance. It is front-loaded with relatable examples and ends with concrete alternatives, making it dense but 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?

With no output schema, the description fully explains the return value (category-bucketed example questions with tool + argument shape). It covers the primary use case, how to call with no arguments or with a topic, and its role in learning about meta-tools. For a simple one-parameter tool, this is complete.

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

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

Schema coverage is 100% and the schema's description of the `topic` parameter already lists the allowed values and the omit behavior. The description echoes this with additional examples but does not add significantly new meaning beyond what the schema provides, so a baseline of 3 is appropriate.

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

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

The description states a specific verb+resource: it returns category-bucketed example questions with the exact tool and argument shape, acting as the onboarding entry point. It clearly distinguishes its purpose from siblings like discover_tools by emphasizing its role as the introductory guide for what to ask.

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

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

Explicitly instructs to 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to focus with a topic parameter. It also names specific meta-tools (ask_pipeworx, entity_profile, compare_entities) as alternatives to learn from, providing clear when-to-use guidance.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses two critical behaviors: ownership is enforced, and the row is deactivated rather than deleted, preserving history in recent_alerts. This adds meaningful context not captured by the schema or 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 succinct sentences: the first states the action, the second explains the side effect. No wasted words, front-loaded with the verb and resource.

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

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

The description explains the purpose, ownership constraint, and deactivation side effect. There's no output schema, but for a simple one-parameter cancellation tool, the description is sufficient. It could mention return values or confirmation, but that's minor given the tool's simplicity and comprehensive annotations.

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

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

Schema coverage is 100%, so the parameter is well-described. The description adds value by explaining that the id is your own subscription (ownership enforcement), and that it's a subscription id returned by subscribe. This clarifies the semantic context beyond the schema's simple type.

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

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

The description uses the specific verb 'Cancel' and resource 'subscription by id', clearly distinguishing from sibling tools like subscribe, list_subscriptions, and recent_alerts. It states the core action unambiguously.

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 contextual guidance by stating ownership enforcement and the deactivation behavior, which tells the agent when it's appropriate to call (to cancel a subscription you own). However, it doesn't explicitly name alternative tools or describe when-not-to-use scenarios, though the context makes this inferred.

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

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

Beyond the read-only/idempotent annotations, the description explains the two execution paths (SEC EDGAR fast path vs. grounded pipeline) and details the semantics of each verdict, especially the critical warning that could_not_verify is not evidence and must not be shown as one. This is significant behavioral context beyond the annotations.

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

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

The description is well-structured with clear sections: example phrasings, usage, pipeline explanation, return values, and important caveats. It's somewhat long and the initial list of paraphrases is redundant, but every substantive piece 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?

With no output schema, the description fully specifies the return verdicts, the actual value with citation, reasoning, and the special error semantics for could_not_verify and unsupported. It also explains the routing rules for different claim types, making it complete for a two-parameter tool.

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

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

Schema description coverage is 100%, so the schema fully documents both `claim` and `tolerance_pct`. The description adds example claims but doesn't add further parameter-level detail beyond what the schema already provides, meeting the baseline for high coverage.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with sample query phrasings. It distinguishes itself from siblings by specifying the two-pipeline approach for financial vs. other claims, making it unique among the listed tools.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also notes it replaces 4–6 sequential calls. However, it doesn't mention when not to use it or name alternatives like ask_pipeworx or deep_research, so it lacks the full when-not/alternatives 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 and idempotentHint=true, so the description adds behavioral detail about checking structure and check digit. It doesn't disclose the return format or error behavior, but with annotations covering safety, a 3 is appropriate.

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 one-sentence description is front-loaded with the action and includes an example. It is concise and every word contributes to understanding, with no wasted text.

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

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

For a simple validation tool with one parameter and no output schema, the description conveys the core behavior. It doesn't explicitly state the return value but implies a validity check, which is sufficient given the low complexity and annotations.

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

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

The schema covers the cusip parameter fully with 100% coverage, including length and example. The description reinforces the format but doesn't add substantial new semantics beyond what the schema already provides.

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

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

The description uses the specific verb 'Validate' with the resource 'CUSIP' and details that it checks structure and the check digit. This clearly distinguishes it from sibling tools like validate_isin and cusip_to_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 clearly indicates the tool's purpose for validating a CUSIP identifier. However, it does not explicitly mention alternatives or when not to use it, so it provides clear context but lacks exclusions.

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

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

The description goes beyond the readOnlyHint and idempotentHint annotations by disclosing that the tool is keyless/offline, works without network or auth, and explicitly states the limitation of not resolving the issuer. It also details the validation logic (structure and mod-10 check digit) and what it returns (ISO country prefix and NSIN), providing rich behavioral context.

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

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

The description is highly concise, consisting of two sentences with no wasted words. It front-loads the main verb ('Validate an ISIN') and immediately provides essential details (format, example, validation method, returns, and limitations). 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?

For a simple single-parameter tool, the description covers purpose, validation logic, return value components, authentication needs, and limitations. It does not specify the exact output structure (e.g., whether it returns a boolean or an object with fields), but the absence of an output schema makes this a minor gap. Overall, it is quite 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?

The schema already fully describes the 'isin' parameter as 'A 12-character ISIN, e.g. "US0378331005"' with 100% coverage. The description reinforces this with the ISO 6166 reference and example, but adds no additional parameter-level semantics beyond what the schema provides. This aligns with the baseline of 3.

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

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

The description clearly states the tool's purpose: validating an ISIN by checking structure and the mod-10 check digit, and returning the ISO country prefix and NSIN. It specifies the exact resource (ISIN) and action (validate), and distinguishes itself from siblings like validate_cusip by focusing on ISIN and explicitly noting it does not resolve the issuer.

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

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

The description provides clear context for when to use the tool (validating ISINs) and notes that it is keyless/offline, suggesting no authentication needed. It also states a key exclusion ('does NOT resolve the issuer'), which implicitly tells the agent not to use this for issuer resolution. However, it does not explicitly name alternative tools for issuer resolution, so it falls short of the highest score.

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