Securitytrails

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds specific behavioral details: probing LLMs, per-model response format, cost implication for Anthropic calls, and default model. No contradictions. Missing details on error handling or rate limits, but transparency is above average.

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

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

The description is two sentences, front-loading the main action and output. Every sentence adds value: action, default, optional key, return structure, use cases. 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?

Given 4 parameters, no output schema, the description covers the return format (per-model score, confidence, signals, raw_response + combined view) and key behavioral aspects like free default and BYO key. It does not detail error scenarios or calculation methodology, but is sufficient for invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by specifying default model for 'models', cost context for '_apiKey', and usage context for 'entity' and 'context'. This extra guidance raises the score above minimum.

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

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

The description clearly states the tool probes LLMs for AI visibility and scores it 0-100 per model. It specifies the default model and optional Anthropic integration, with return structure. While siblings like scan_competitor_ai_presence exist, the purpose is self-contained and distinct.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the optional _apiKey. It does not explicitly exclude alternatives or compare to siblings, but the context is clear enough for selection.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description builds on this by explaining that the tool routes internally, fills arguments, returns structured answers with citation URIs, works on every tier, and is a single fast call. It also notes that it covers live news and other packs, adding meaningful behavioral detail beyond annotations.

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

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

The description is longer than a typical tool description but is front-loaded with a strong directive ('PREFER OVER WEB SEARCH') and every sentence provides actionable guidance. It is dense with useful information, including examples and alternative routing, though some redundancy exists (e.g., repeating the guidance to prefer over web search). Overall it is well-structured and earns its length.

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

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

Given the tool's complexity (routing to thousands of sources), the description is comprehensive. It covers what it does, when to use it, examples, output characteristics (structured answer with citation URIs), and explicit comparisons to siblings. Since no output schema exists, the description adequately explains what the agent can expect from the tool.

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

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

Schema coverage is 100%, with the question parameter fully described and aliases listed. The tool description adds example questions but does not provide additional parameter syntax or semantics beyond the schema. Per the baseline for high schema coverage, a score of 3 is appropriate.

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

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

The description clearly states the tool's function: routing questions to one of 5,529 tools across 1,455 verified sources and returning a structured answer with stable citation URIs. It uses a specific verb ('routes') and resource ('questions'), and explicitly distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research.

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

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

Usage guidance is explicit and rich. It says 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and gives exact conditions for stepping up to alternatives ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). It also lists trigger phrases and examples, making it clear when this tool is the right choice.

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

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

The description goes beyond annotations by explaining that candidate routing improvements are enabled live only when under test, that none is active now, and that the tool currently matches ask_pipeworx exactly. It also states it is a full working router with no fallback, and that outputs are compared to the stable router—valuable behavioral context not captured in the safety 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 four sentences and each clause adds relevant information: beta status, current equivalence, usage direction, and reassurance of full functionality. Slightly more verbose than strictly necessary but well-structured and front-loaded with the key 'beta' designation.

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

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

Despite no output schema, the description covers the tool's role, current state, relationship to the stable version, and usage guidance. It also references the response shape being identical to ask_pipeworx, making the context complete for a single-question parameter tool with rich 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?

With 100% schema coverage, the schema already documents the question parameter and its five aliases. The description only says 'same arguments as ask_pipeworx' without adding new semantic detail, so the baseline 3 applies.

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

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

The description identifies this as a beta version of ask_pipeworx, a universal router over 5,529 tools, and distinguishes it from the stable ask_pipeworx by its experimental routing improvements. It clearly states the resource (beta router) and implies the action (answer/route questions). The reference to identical arguments and response shape clarifies functional equivalence.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and contrasts results against the stable router, giving a clear condition for selection. It lacks an explicit 'when not to use' but the beta/experimental framing implies caution for production use.

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

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

Annotations already declare readOnly/idempotent, but the description adds substantial behavioral context: return shape with evidence and confidence, refusal reasons enumerated, and the extra LLM call cost. It also discloses the grounded extraction constraint, going far beyond what annotations provide.

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

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

Three sentences, each densely informative: purpose, return/refusal behavior, and usage guidance. Front-loaded with the key phrase 'Hallucination-resistant answer mode', no wasted words despite covering multiple aspects.

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

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

Despite no output schema, the description fully specifies the success and refusal return formats, lists all refusal reasons, explains the routing and extraction process, and provides use-case guidance. It is complete for a tool with this complexity.

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

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

Schema coverage is 100% and every parameter is an alias for 'question' with additional description in the schema. The tool description does not add parameter-specific meaning, but it also does not need to since the schema is complete. 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 it is a 'hallucination-resistant answer mode' for high-stakes reads, with a specific verb-resource pairing. It explicitly distinguishes itself from ask_pipeworx by explaining it extracts answers using ONLY the tool result and returns evidence/refusals, making it unique among siblings.

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

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

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on... must not invent facts') and when not to ('prefer ask_pipeworx for casual lookups'), including cost tradeoff. This gives clear decision rules versus the sibling ask_pipeworx.

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 details behavioral traits beyond annotations. It explains parallel fan-out to category-specific data packs, response shapes (result.market, result.analysis, result.evidence), safety mechanisms (low-confidence short-circuit, closed market handling, wide-spread warnings), and resolution-rule risk (cancellation rules). It also covers fallback behavior for news fields. Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent. This level of transparency is exceptional.

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 (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Each section adds necessary detail for a complex tool. While slightly verbose, the organization helps agents quickly locate relevant information. A score of 4 reflects good structure with minor length concerns.

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

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

Given the tool's complexity (multiple data sources, resolution logic, edge cases), the description is comprehensive. It covers response shapes for market, analysis, evidence, parent events, news fields with fallback, safety short-circuits, closed/inactive markets, wide-spread liquidity warnings, and cancellation rule interpretation. No output schema exists, but the description fully explains expected return values. Score 5 for thoroughness.

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%. Each parameter (market, depth, include_raw) has a clear description in the schema. The description adds value by providing examples in the schema and explaining depth behavior ('quick = 2-3 evidence sources, thorough = full fan-out') and include_raw use cases. It also includes fan-out examples that implicitly clarify depth. This goes beyond the schema, earning a 4.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and outlines the process (resolve, classify, fan out, return evidence packet + comparison). While it does not explicitly distinguish from sibling tools like polymarket_arbitrage or polymarket_edges, the verb 'research' and detailed workflow differentiate its intent. A score of 4 reflects clear purpose but no explicit sibling differentiation.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives examples of fan-outs for various bet types (BTC, Fed, Hormuz, etc.), guiding when to use the tool. It advises inspecting market_match_confidence before trusting analysis. However, it does not state when NOT to use it or suggest alternative tools. Score 4 for clear usage context with minor gaps.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. Description adds specific data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/clinical trials for drugs), sorting by primary metric, and return format (paired data with citation URIs). No contradictions.

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

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

5-6 sentences, front-loaded with trigger phrases and core purpose. Every sentence adds value—no filler. Efficiently packs examples, use cases, data sources, and return format.

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

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

No output schema exists, but description explains return format (paired data + citation URIs) and sorting. Covers purpose, parameters, data sources, and usage guidance. Fully adequate for an AI 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?

Schema coverage is 100%, but description adds meaning: for 'type' it details what data is retrieved per entity type, for 'values' it specifies format (tickers/CIKs vs drug names) and constraints. This goes beyond the schema's brief descriptions.

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

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

Description clearly states it performs side-by-side comparisons of 2-5 companies or drugs in one call, with trigger phrases like 'compare X and Y'. It distinguishes from sequential lookups by stating 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', which differentiates it from sibling tools 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?

Provides explicit triggers ('compare', 'versus', 'which is bigger') and context (when comparing entities, prefer over sequential lookups). Lacks explicit 'when not to use', but the guidance is strong and clear enough.

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

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

Adds rich behavioral context beyond annotations: account requirements, paid tier for 'thorough,' latency expectations, parallel routing to 5,529 tools, return packet structure, gaps[] behavior, contradictions[] for standard/thorough, citation_uri being always fetchable, and semantic excerpting. This goes far beyond the readOnly/openWorld/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 long but each sentence earns its place, covering essential constraints, examples, and edge cases. It is front-loaded with the most critical information (account requirement) and uses clear separators. However, it is verbose enough that a more concise version could still preserve value, so not a perfect 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?

Despite lacking an output schema, the description thoroughly explains the return format (findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[] for unanswered facets, contradictions[], and hop fields. It also covers edge cases, latency, and account limitations, making it fully self-contained for an agent.

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

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

Schema coverage is 100%, providing baseline 3. The description adds meaningful semantics for 'depth' by elaborating on what standard (gap recovery) and thorough (lead chasing) actually do, and clarifies that 'question' can be broad/multi-part. This extra context elevates the score above baseline.

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

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

The description clearly states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explains the decomposition process. It distinguishes from siblings by explicitly contrasting with ask_pipeworx for single lookups and news topics, making the tool's unique role 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?

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data,' and not-for-use cases: 'For a single lookup use ask_pipeworx,' 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' Also includes account tier conditions and fallback when not signed in, making usage boundaries crystal clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the bar is lower. The description adds valuable context: returns top-N relevant tools with full schemas and examples, ready to call directly, with no need for second schema lookup. This provides useful behavioral promise beyond annotations.

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

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

Three sentences are efficient and front-loaded: first sentence states purpose, second gives usage context with examples, third explains output and recommendation. Very minor wordiness but overall well-structured.

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

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

The description covers purpose, when to use, output details (top-N tools with schemas and examples), and usage recommendation. Given the tool's complexity as a discovery interface, it is complete and actionable, even without an output schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add additional parameter meaning beyond what the schema already provides; it lists example domains for context but not parameter-specific semantics.

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

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

The description clearly states the tool finds tools by describing data or task, using specific verbs like 'find' and 'discover'. It lists many example domains (SEC filings, FDA drugs, etc.), differentiating it from sibling tools as a meta-tool for exploration.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover' and recommends calling it FIRST when many tools are available, providing clear when-to-use guidance and implying alternatives are for specific known tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds significant context: fans across multiple data sources, returns specific fields (cik, recent_filings with URIs, fundamentals, patents, news, LEI), and notes that patents endpoint 'soft-fails until reactivated.' No contradiction with annotations.

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

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

Description is fairly long but every sentence adds useful information. Front-loaded with example queries. Could be slightly more structured but remains focused and 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?

No output schema exists, so description needs to explain return values. It does so thoroughly, covering all key components (cik, filings, fundamentals, patents, news, LEI). Omits error handling details but is sufficient for a profile tool.

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

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

Schema coverage is 100%, baseline 3. Description adds value by stating 'type' is only 'company', 'value' is ticker or zero-padded CIK, and explicitly says names not supported, with examples ('AAPL', '0000320193'). This enhances understanding beyond the schema.

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

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

Description starts with typical user queries like 'Tell me about X' and clearly states it returns a 'full cross-source profile of a US public company in ONE parallel call.' This precisely identifies the verb (profile) and resource (US public companies), and the use of 'ALWAYS PREFER' distinguishes it from siblings like compare_entities or resolve_entity.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also provides a clear exclusion: 'names not supported (use resolve_entity first if you only have a name).' This gives both when-to-use and when-not-to-use guidance with an 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 provide destructiveHint:true and idempotentHint:true. Description adds context about stale data or clearing sensitive info but doesn't contradict 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 front-loaded sentences with zero waste. Every phrase serves a purpose.

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

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

For a single-parameter, no-output-schema tool with annotations, the description covers purpose, usage context, and tool pairing comprehensively.

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

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

Schema coverage is 100% and description does not add information beyond the schema's definition of 'key' as 'Memory key to delete'. Baseline 3 applies.

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

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

Description clearly states 'Delete a previously stored memory by key', a specific verb-resource pair. It distinguishes from siblings 'remember' and 'recall' by focusing on deletion.

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

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

Explicit guidance on when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Suggests pairing with 'remember' and 'recall', though does not explicitly mention when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds specific behavioral details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' No contradictions with annotations.

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

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

The description is four sentences with no wasted words. It front-loads the core purpose, follows with how it works, and ends with practical use cases.

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 two simple parameters, rich annotations, and no output schema, the description fully covers purpose, behavior, output format, and usage scenarios. It mentions the output is 'a single text blob ready to drop at site-root/llms.txt'.

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

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

Both parameters (url, max_links) are fully described in the input schema (100% coverage). The description does not add meaning beyond what is already in the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states 'Generate a production-ready llms.txt file for any URL', specifying the verb 'Generate', the resource 'llms.txt', and the target 'URL'. It distinguishes itself from sibling tools like scan_competitor_ai_presence or ai_visibility_check by focusing solely on llms.txt generation.

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

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

The description explicitly lists 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.' This provides clear context for when to use the tool, though it lacks explicit 'when not to use' guidance.

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

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

Annotations already declare readOnly=true and destructive=false; description adds return fields and default 'active' scope. Does not contradict 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 efficient sentences with purpose first. No redundancy, every phrase adds value.

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

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

For a simple list tool (one optional param, no output schema), the description fully covers purpose, return fields, and usage context.

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

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

Schema coverage is 100% with clear description for 'include_inactive'. Description adds no extra meaning beyond schema.

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

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

Verb 'list' + resource 'subscriptions' clearly stated. Returns specific fields, distinguishing from siblings like 'subscribe' and 'unsubscribe'.

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

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

Explicitly says when to use: 'review what you're monitoring before adding more or to find an id to cancel'. Does not explicitly exclude alternatives but context strongly implies when not to use.

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

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

The description adds rich behavioral context beyond annotations: rate limiting (5/day), the claim_token flow for anonymous tracking, that the team reads digests daily, and that it's free and doesn't consume quota. These details are not visible in annotations or schema and help the agent predict side effects and constraints.

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 meaningful guidance: purpose, use cases, exclusions, mechanics, and limits. It is front-loaded with the primary action, and the additional details (rate limit, token behavior) are placed where they naturally extend the workflow without padding.

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 covers the essential workflow: how to file, what happens anonymously (claim_token), how to follow up, and behavioral constraints. The nested context object is described sufficiently through schema, and the description ties all pieces together for a complete understanding.

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 explaining the claim_token round-trip workflow and advising users to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts, which supplements the schema definitions with usage nuance.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback channel from sibling tools by scoping it to Pipeworx-served tools and explicitly contrasting with other MCP servers.

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 for each category (bug, feature/data_gap, praise) and a clear exclusion: tools from other MCP servers should be filed elsewhere. It even tells users how to disambiguate ('Pipeworx tool names are the ones this connection lists'), going beyond simple context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds valuable context: data source (CF analytics-engine), no PII, and caching policy (5min-1h). No contradictions.

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

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

Three sentences, each with distinct purpose: result, use cases, technical details. Front-loaded with main purpose. No redundant information.

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

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

The description conveys the output concept (top tools, packs, call volume) but lacks explicit return structure or formatting. Given the tool’s simplicity and the presence of annotations, completeness is good but not exhaustive.

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

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

Schema coverage is 100% for the single enum parameter. The description adds meaningful context by explaining how different windows affect results (short-term vs steady-state), enhancing the schema's basic description.

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

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

The description clearly states it returns top tools, top packs, and total call volume over recent windows, using the specific verb 'returns' and resource 'trending data'. It distinguishes from siblings like 'discover_tools' by focusing on real-time usage.

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

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

Three explicit use cases are provided, offering clear guidance on when to use this tool (e.g., discovering hot data sources, confirming popular tools). However, it does not explicitly state when not to use it or mention alternatives, such as 'discover_tools' for general discovery.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds rich behavioral context: fill check against live CLOB depth, realizable_edge_pp interpretation, partition signal behavior, and conditions like Jaccard similarity. No contradiction with annotations.

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

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

Description is somewhat long but well-structured: first sentence states purpose, then explains modes, then fill check. Every sentence adds value, though it could be more concise for an agent. Still, organization is clear.

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

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

Given complexity (two modes, fill check, semantic constraints) and no output schema, the description comprehensively explains inputs, output structure (opportunities[] fields), and conditions for valid trades. Covers all major aspects.

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 both parameters with descriptions (100% coverage). Description adds examples and clarifies semantics: event expects a Polymarket event slug, topic expects a seed question. This goes beyond the schema but baseline is 3 due to high coverage.

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

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

Description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between two modes (event and topic) and explains each, differentiating it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly tells when to use each mode: call with no args for trending scan, pass event for single-event, pass topic for cross-event. Explains benefits of cross-event mode and provides conditions like semantic anchor and partition filter. References sibling tool polymarket_fill_risk for custom sizing.

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

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

The description goes far beyond annotations by detailing model methodologies (e.g., lognormal barrier, GDELT ratio, partition overround), caching behavior ('Cached 1h at KV level'), and diagnostic output. It explains edge calculation, slippage assumptions, and caveats like Fed bets being excluded. No contradictions with annotations (readOnlyHint, idempotentHint, etc.).

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

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

The description is dense and information-rich, but it justifies its length by covering complex model families, response structure, and knobs. It is front-loaded with purpose and well-organized, though slightly verbose. Every sentence adds value, making it efficient for the complexity.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics) and key fields (edge_pp_net, kelly_fraction, etc.). It covers caching, filter knobs, and diagnostic counters. No significant gaps are present given the tool's complexity.

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

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

Schema coverage is 100% with detailed descriptions for all 9 parameters. The tool description adds minimal additional parameter-level meaning, mostly reinforcing the schema. Some extra context is provided (e.g., slippage_pp mentions zero trading fees), but overall the description does not significantly enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool scans Polymarket markets for edge opportunities where Pipeworx data disagrees with market price. It explicitly distinguishes itself from siblings like 'polymarket_arbitrage' by focusing on model-driven, structural arbitrage, and concentrated longshot opportunities, making its purpose specific and unambiguous.

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

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

The description provides a clear use case ('what should I bet on today') and explains when to use it (to discover opportunities without paging through markets). However, it does not explicitly state when not to use it or directly compare to alternative tools, though the categorization of segments suggests 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?

Adds significant detail beyond annotations: explains snapshot-based data, return structure (tracked/expired/snapshot_dates), decay computation method, TTL limits, and gaps. No contradictions.

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

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

Well-structured with labeled sections (RESPONSE, LIMITS) and front-loaded main purpose. Slightly verbose, but justified by complexity and lack of output schema. One sentence could be trimmed.

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

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

Given no output schema, description thoroughly documents all return fields, edge cases (gaps, TTL), and limitations. Covers every aspect an agent needs to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds minor context (snapshot family, clamp range) but mostly mirrors schema, not adding meaningful new semantics.

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

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

Description uses specific verbs and nouns: 'Edge persistence and decay telemetry', answers a clear question, and distinguishes from sibling polymarket_edges by focusing on historical analysis.

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

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

Implied usage via examples (fresh vs old edge) and parameter explanations, but lacks explicit when-to-use or alternatives. No mention of when not to use or why one would choose this over 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 declare readOnlyHint=true, destructiveHint=false, etc., so the safety profile is clear. The description adds detailed behavioral context: walks the order book ladder, returns slippage, fill details, and risk warnings about thin books and partial fills. Enhances transparency beyond annotations.

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

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

The description is lengthy but well-structured with clear sections and all-caps emphasis. Every sentence serves a purpose, though it could be slightly more concise. Front-loaded with purpose and mode distinction.

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

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

Given the tool's complexity (two modes, multiple return fields, no output schema), the description is thorough: explains both modes, key return fields, risk of partial fills, and usage prerequisites. Completely covers what an agent needs to use effectively.

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

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

Schema description coverage is 100% with basic parameter meanings. The description adds extra semantics: clarifies size_usd for basket mode as settlement notional, and explains side default behavior for basket. This adds 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 checks realizable vs theoretical edge against live order book depth, distinguishes between single-market and basket modes, and mentions specific return fields. It differentiates itself from siblings by explicitly stating when to use it before polymarket_arbitrage or polymarket_edges trades.

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

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

The description provides explicit when-to-use guidance: before acting on arbitrage signals or edges trades above ~$500. It explains why (theoretical overround not capturable, partial fills cause directional risk) and gives mode selection criteria.

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

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

Annotations include readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds detailed behavioral context: explains two modes, safety fields (compatibility_warning, temporal_alignment, skipped counters), and interprets results. No contradiction with annotations.

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

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

The description is long but every sentence adds value. It is front-loaded with the core purpose. Could be slightly more concise but the complexity justifies the length.

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

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

Given the tool complexity, 3 parameters, and no output schema, the description thoroughly explains the response structure (leg-by-leg prices, top_spreads_pp, safety fields) and edge cases (compatibility_warning conditions). No missing critical information.

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

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

Schema coverage is 100%. The description explains what each parameter does: topic as pre-mapped shortcuts, kalshi_event_ticker and polymarket_event_slug as overrides. Adds meaning beyond schema by explaining override behavior and providing 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage and provides specific details about two modes (topic and explicit).

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

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

Explicitly says when to use (compare prices across venues), warns about rarity of real spreads and that pre-mapped doesn't mean tradeable. Implicitly guides when not to use via safety fields like compatibility_warning. No direct alternative mentioned but sibling context makes it clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context: scoping to identifier, listing behavior, and pairing with remember/forget. No contradiction.

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

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

Two sentences with no wasted words. Front-loaded with core function and alternative use in the first sentence; second sentence adds purpose and pairing context.

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

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

For a tool with one optional parameter, no output schema, and clear annotations, the description fully covers behavior (retrieve, list, scoping) and pairing with siblings. No gaps.

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

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

Schema coverage is 100%, explaining the 'key' parameter. The tool description restates this but does not add new semantic details beyond the schema, meeting the baseline expectation.

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

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

The description specifies the verb 'retrieve' or 'list', the resource 'values saved via remember', and distinct behavior when key is omitted. It clearly distinguishes the tool from siblings like 'remember' and 'forget'.

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

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

The description states when to use the tool ('look up context stored earlier') and how to list all keys (omit key). It implies alternatives by mentioning 'remember' and 'forget' but does not explicitly list when not to use the tool.

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

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

Describes the mark_read side effect that affects subsequent calls, which adds context beyond readOnlyHint annotation. No contradictions with annotations; discloses behavior clearly.

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?

Very concise; front-loaded with main function, each sentence adds information without redundancy. No wasted words.

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

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

Covers return fields, filtering, side effects, and alternative endpoint. For a simple read tool with no output schema, this is reasonably comprehensive.

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

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

Schema has 100% coverage, but description adds meaningful context: example filter type 'sec_8k', ISO timestamp format, and explanation of mark_read's effect. Adds value beyond schema.

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

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

Clearly states it pulls fired events from subscription feed, returns alerts with specific fields, and supports filtering. Distinguishes from siblings by mentioning an alternative GET endpoint for scripts, but does not explicitly differentiate from other related 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?

Explains filtering by type and since, the mark_read flag, and notes that polls work fine. Mentions an alternative endpoint for other use cases, but lacks explicit when-to-use vs siblings.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive. Description adds details on GDELT→GNews fallback, USPTO soft-fail, and return structure (changes grouped by source, count, 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?

Description is a single dense paragraph with efficient use of examples and details. Slightly long but every sentence adds value.

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

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

No output schema, but description explains return fields. Covers multi-source behavior, fallback, and soft-fail. Could mention handling of empty 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 has 100% coverage. Description adds examples for since (ISO date and relative shorthand, including recommendation), constrains type to 'company', and explains value as ticker or CIK.

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 a given time window, covering SEC, news, and patents. It distinguishes from sibling tool entity_profile by contrasting dynamic vs. static profiles.

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 example queries (e.g., 'What's new with X') and contrasts with entity_profile for static profile requests. Explains fallback behavior for news sources.

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 context beyond annotations: scoping by identifier, persistence duration for authenticated vs anonymous users. No contradictions with annotations.

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

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

Description is compact and front-loaded with purpose. No redundant sentences, but could be slightly more concise.

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

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

For a simple memory tool, description covers purpose, usage, behavioral aspects, and references sibling tools. No output schema needed.

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

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

Schema coverage is 100%, so baseline is 3. Description adds examples for key naming conventions and value type, but does not significantly enhance meaning beyond schema.

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

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

Description clearly states verb 'save' and resource 'data the agent will need to reuse later', with specific examples like 'resolved ticker, target address'. Differentiates from siblings by referencing recall and forget.

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

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

Explicitly says when to use: 'Use when you discover something worth carrying forward'. Provides context on scoping and persistence. Could further mention when not to use, but complementary tools are implied.

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

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

The description discloses behavioral traits beyond annotations, such as labeling identifiers with their source, explicitly listing unresolved identifiers under `unresolved`, and gracefully degrading LEI/FIGI enrichment if upstream providers fail. This adds valuable context on error handling and data provenance, exceeding what the annotations already cover.

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

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

The description is verbose but information-dense, covering many details within a few sentences. It is front-loaded with example queries, though the core purpose statement appears midway. The structure is acceptable given the tool's complexity, but could be streamlined with bullet points.

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

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

For a tool with only two parameters and no output schema, the description is thorough: it lists return identifiers, source attribution, unresolved handling, graceful degradation, and the internal cascading nature. It leaves minimal ambiguity about what the tool does, what it returns, and how it behaves in edge cases.

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

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

Schema coverage is 100%, but the description enriches parameter meaning by explaining what each accepted input type resolves to (e.g., company returns CIK, ticker, LEI; drug returns RxCUI). It also provides additional example values and clarifies the scope of each parameter beyond the basic schema.

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

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

The description explicitly states the tool 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input' and provides concrete examples like 'ticker', 'CIK', 'LEI'. It clearly distinguishes this from sibling tools by focusing on identifier lookup, while tools like entity_profile or compare_entities serve different purposes.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also clarifies that it replaces '2-3 manual lookups', implying direct use. However, it does not explicitly mention when not to use it or alternative tools, though the differentiator is implicit.

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 as false. The description adds behavioral context: it probes each entity with ai_visibility_check, ranks results, and returns a ranked list with score, confidence, and signal density. It also notes that the first entity is treated as the 'subject' for narrative. No contradictions with annotations.

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

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

The description is two sentences long, no wasted words. The first sentence immediately states the core action and benefit. Every sentence adds value and 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?

Given no output schema, the description adequately covers what the tool returns (ranked list with score, confidence, signal density). It explains the workflow, how the context parameter is used, and the subject role of the first entity. Annotations fill in safety and idempotency. The description is complete for the tool's complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: it explains that the first entity in the array is treated as the 'subject' for narrative, and describes the output format (ranked list with score, confidence, signal density). It also clarifies that the context parameter is shared across probes for disambiguation.

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: 'Compare AI visibility across multiple entities side-by-side.' It specifies the action (probing each entity with ai_visibility_check), the resource (entities), and the output (ranked list with scores). It distinguishes itself from the sibling ai_visibility_check by being a comparative wrapper.

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

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

The description explicitly states when to use: 'Useful for competitive AI-marketing audits' and provides an example question. It implies that for single entities, one should use ai_visibility_check, but does not explicitly say when not to use this tool. That omission prevents a score of 5.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds that partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists timeouts. No contradictions.

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

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

Single paragraph is reasonably concise for the amount of information. Front-loaded with purpose, then details. Could be slightly more structured but no wasted sentences.

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

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

For a tool with no output schema, the description thoroughly explains return structure: summary block fields, per-advisory detail, links, alternative versions. Also covers edge cases like partial failures and timeouts.

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

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

Schema has 100% coverage for both parameters. Description adds that scoped packages are accepted and version defaults to latest. Also explains how parameters are used in the composite check.

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 does a composite check for adding an npm package, covering license, advisories, version history, and bundle size. It is distinct from all sibling tools listed.

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

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

Explicitly states when to use: 'whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. It also notes ecosystem limitation and directs to deps.dev for other ecosystems.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds beyond: embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), char cap (200K truncation with flag), and that each passage carries an offset for verification. No contradictions.

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

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

The description is four sentences, well-structured: purpose, usage scenario, pairing with sibling, and technical details. Every sentence is informative and earns its place. No fluff.

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

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

Despite lacking an output schema, the description explains the return format (top-N passages, character offsets, similarity scores). It also covers technical constraints (char cap, truncation behavior, embedding model). For a search 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% with descriptions for all three parameters. The description adds value by providing richer context: examples of what text could be (e.g., SEC 10-K body), that query is natural language with specific examples, and that limit returns top-N passages. This goes beyond the schema's short descriptions.

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

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

The description clearly states the tool does semantic search inside a fetched record, with specific examples (SEC 10-K body, article, long tool result) and explains the output (top-N passages, character offsets, similarity scores). It distinguishes from siblings like ask_pipeworx_grounded, which is paired with this tool.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt' and 'saves context, returns only the passages that matter.' It also mentions an alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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. Description adds context with example and clarifies return includes first/last-seen dates, but does not disclose potential rate limits, API key usage nuances, or result volume.

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

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

Two sentences plus an example, all essential. Information is front-loaded and no wasted words.

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

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

No output schema exists, and description only mentions 'returns past record values with first/last-seen dates' without specifying structure (e.g., array of objects). Adequate but could detail return format more thoroughly.

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

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

Schema coverage is 100%, so baseline is 3. Description provides an explicit example showing parameter usage and lists record types, adding meaningful context beyond the schema 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?

Description clearly states the tool retrieves historical DNS records for a hostname, listing supported record types and return values. It distinguishes from sibling tools like securitytrails_domain (current data) and securitytrails_subdomains.

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

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

Implies usage for historical DNS lookup via example, but does not explicitly state when to use this tool versus alternatives or when not to use it. No context on prerequisites or constraints.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, so the safe, read-only nature is clear. The description adds value by detailing the specific return data (DNS records, subdomain count, Alexa rank), which is not covered by annotations. No contradictions.

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

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

The description is two sentences plus an example, with no unnecessary words. It front-loads the purpose and immediately provides a concrete usage example. Every sentence earns its place.

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

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

Given the tool has only two parameters, no output schema, and clear annotations, the description fully covers what the agent needs: what it does, what it returns, and how to call it (example). No gaps remain.

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

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

Schema coverage is 100% with descriptions for 'hostname' and '_apiKey'. The description provides an example call but does not add new semantic meaning beyond the schema. 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 specifies the tool returns current A/MX/NS records, subdomain count, and Alexa rank for a given hostname. It clearly differentiates from sibling tools like securitytrails_dns_history (historical DNS) and securitytrails_subdomains (listing subdomains) by focusing on current domain intel.

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 use for current DNS and ranking data, but does not explicitly state when to prefer this over siblings (e.g., history vs. current; subdomains vs. overview). Agent must infer from sibling names. No explicit when-not or alternatives mentioned.

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

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

Annotations already declare idempotent and read-only behavior. The description adds useful context about the return format (subdomain labels plus fully-qualified domains), which is beyond what annotations provide.

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

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

Two sentences, no wasted words. The verb and resource are front-loaded, and the example is compact.

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 enumeration tool with robust annotations, the description is complete: it states purpose, input, and output format. No output schema exists, so the description's mention of return value is 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%, so the schema already describes both parameters. The description adds a concrete usage example showing parameter values, which aids understanding beyond the schema.

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

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

The description clearly states the verb 'Enumerate' and resource 'subdomains of <hostname>'. It distinguishes from sibling tools like securitytrails_domain and securitytrails_whois by focusing specifically on subdomain enumeration.

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?

No guidance is given on when to use this tool versus alternatives such as securitytrails_dns_history or securitytrails_domain. The agent must infer usage from the tool name alone.

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

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

Annotations already declare readOnlyHint and idempotentHint; the description adds value by specifying the exact return data (registrar, dates, contacts). No contradictions.

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

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

Description is concise: one sentence stating purpose and output, plus a clear example. No redundant or unnecessary 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 full schema coverage, comprehensive annotations, and a clear description, the tool definition is complete for safe and effective use. The example aids understanding.

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 both parameters with descriptions. The description adds an example but no additional semantic meaning beyond what the schema provides. Baseline score applies due to 100% 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?

Clearly states the tool retrieves WHOIS data for a hostname, specifying the exact output fields (registrar, dates, contacts). Distinguishes from sibling tools like securitytrails_dns_history and securitytrails_subdomains by its unique resource.

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 example call but does not explicitly guide when to use this tool versus related sibling tools (e.g., securitytrails_domain). Usage context is implied but not directly stated.

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 provide readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: account requirement, SMS cap, webhook signing secret and auto-disable, and type-specific behaviors. It does not confirm the idempotent hint, but overall adds value beyond annotations.

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

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

The description is relatively long but each sentence adds useful information. It front-loads the main purpose and return value. Could be slightly more concise, but efficiency is good given the complexity.

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

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

Given three parameters with nested objects, no output schema, and multiple subscription types, the description is thorough. It explains all delivery channels, type-specific params, and return value (subscription id). It covers the necessary context for an AI agent to use the tool correctly.

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

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

Schema coverage is 100%. The description provides detailed examples for each type in params, and explains delivery channels with additional constraints and behaviors (e.g., webhook HMAC signing, auto-disable). This goes well beyond the schema descriptions.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses a specific verb (create) and resource (subscription), and distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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 specifies prerequisites ('Requires a Pipeworx OAuth account'), delivery options with constraints (SMS must be verified, 10/day cap, webhook auto-disable), and type-specific parameters. It does not explicitly state when not to use, but the context is clear enough for an AI 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by describing the output structure (category-bucketed example questions with exact tool+argument shape) and that it draws from a live catalog, going beyond what annotations provide.

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

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

The description is a single dense paragraph but well-organized: it starts with common queries, explains the tool, lists categories, and then describes parameters and usage. It could be slightly more concise but is front-loaded with the tool's purpose.

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

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

Given that there is no output schema, the description effectively explains what the tool returns and how to use it. It covers the return value structure and the optional parameter behavior, making it complete for a simple tool.

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

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

Schema coverage is 100% with the parameter description listing the focus areas. The description adds additional context by explaining that omitting topic gives a cross-category spread, which is not explicit in the schema. This adds moderate 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 returns category-bucketed example questions for Pipeworx, with a specific purpose as an onboarding entry point. It uses specific verbs like 'returns' and 'draws from', and the title 'What Can I Ask Pipeworx?' aligns perfectly with 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 says 'Use this FIRST when you do not yet know what Pipeworx can do for you', providing a clear when-to-use directive. Also explains the optional topic parameter and the effect of omitting it, giving strong usage guidance.

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

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

Describes beyond annotations: ownership enforcement, deactivation vs deletion, and link to 'recent_alerts'. 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?

Two concise sentences with action first, then behavioral context. No wasted words.

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

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

For a simple tool with one parameter and no output schema, the description explains the effect and side effects. Might benefit from return value info, but overall complete.

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

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

Schema coverage is 100% and description adds no extra semantics beyond the schema's parameter description. 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 uses a specific verb 'Cancel' and resource 'subscription', and clearly distinguishes it from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states ownership enforcement and that deactivation keeps historical events, providing context for when to use. Lacks explicit 'when not to use' but is adequate.

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 readOnly/idempotent annotations, the description discloses the two-route verification logic, the complete set of possible verdicts, and — critically — the semantic distinction between 'could_not_verify' (check failed) and 'unsupported' (no source found), warning that 'could_not_verify' must not be used as evidence. This is valuable behavioral detail that annotations do not capture.

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 the description is long, it is tightly structured with no fluff: trigger phrases at the start, then the use case, pipeline split, output shape, and two important caveats. Every sentence adds unique information, and the progression is logical and front-loaded.

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

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

Given the tool's complexity and the absence of an output schema, the description fully specifies all six verdicts, the included evidence and citation, and the error-handling semantics. Combined with complete parameter schema coverage and clear annotations, this leaves no significant gaps for correct tool invocation and 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?

The input schema already describes both parameters (claim and tolerance_pct) with detailed explanations and defaults, so the description adds little parameter-level meaning. It mentions 'exact percent-delta math' and the tolerance override, but this is more about tool behavior than new parameter semantics, so the baseline 3 applies.

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

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

The description clearly identifies this as a natural-language claim verification tool, with explicit trigger phrases and a stated purpose: checking whether a user's claim is factually correct. It distinguishes itself from sibling Q&A tools by detailing the verdict-based output and the two internal pipelines (SEC EDGAR for financial claims, grounded pipeline for everything else), which is a unique capability.

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 clear usage context: "Use whenever the agent needs to check whether something a user said is factually correct" and lists typical trigger phrasings. It does not explicitly name alternative tools to avoid or state when not to use this tool, though the phrase 'Replaces 4–6 sequential calls' implies it is the consolidated claim-checking choice.

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