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?

Beyond the annotations, the description reveals important behavioral traits: it is a router/orchestrator that selects among thousands of tools, fills arguments, and returns results with stable citation URIs. It also explains that it covers live news and news-feeds packs, which is useful context an agent cannot infer from the annotations alone.

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

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

The description is long but information-dense, and it front-loads the key instruction 'PREFER OVER WEB SEARCH'. The examples and alternative routing rules justify the length, though it could be slightly tightened around the trailing sibling-tool routing paragraph.

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 complex router with no output schema, the description covers what the tool does, when to use it, what it supports, and how it differs from key alternatives. It explains the return style (structured answer with citations) adequately, but leaves minor ambiguity around phrases like 'grounded-off answer' and the exact meaning of '*-news-feeds packs'.

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

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

The input schema has 100% parameter description coverage: the only meaningful parameter, 'question', is fully documented and all aliases are listed. The description adds no parameter-specific semantics beyond general usage guidance, so the schema already carries the necessary weight.

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

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

The description states exactly what the tool does: routes a natural-language question to the most relevant of 5,738 tools across 1,499 verified sources, fills arguments, and returns a structured answer with pipeworx:// citation URIs. It also distinguishes itself from siblings such as ask_pipeworx_grounded and deep_research, so an agent can tell it apart clearly.

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 is explicit about when to use this tool: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', 'START HERE for most questions', and it gives concrete trigger phrases and examples. It also names alternatives and their conditions, such as using deep_research for broad multi-part questions and ask_pipeworx_grounded for grounded-off answers.

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

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

Beyond annotations like readOnlyHint and idempotentHint, the description adds valuable operational context: candidate routing improvements are enabled live only when under test, no candidate is currently active, and it falls back to nothing because it is a full working router. This gives the agent a clear picture of the tool's experimental nature and current behavior.

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

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

The description is moderately sized and front-loaded with the core identity: 'Beta version of ask_pipeworx.' Each sentence contributes meaningful detail, including usage, current status, and operational expectations. The parenthetical date and repeated 'same' phrasing add slight length but help pin down the exact state of the tool.

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

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

For a beta universal router with high complexity, the description covers the key context: equivalence to ask_pipeworx, live experimental behavior, current inactive state, and how results are evaluated. It does not spell out the response shape, but it points to ask_pipeworx as the reference, and the annotations already cover the safety profile, making the definition largely complete.

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

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

Schema description coverage is 100%, so the schema carries the burden for parameter documentation. The description only says 'same arguments' and does not enumerate or explain the parameters beyond what the schema already provides. This is adequate but adds no additional semantic value for parameter understanding.

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

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

The description clearly identifies the tool as a beta variant of ask_pipeworx and states it is an identical universal router with the same 5,738 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx sibling by emphasizing the experimental routing improvements, though it relies on the noun 'router' rather than a direct action verb like 'routes questions to tools.'

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router to decide merges. It also notes the current inactive-candidate status, which clarifies expected behavior. It does not explicitly state when NOT to use it, such as preferring the stable ask_pipeworx for production needs, but the experimental-edge framing implies this.

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

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

Annotations already mark readOnlyHint/openWorldHint/idempotentHint, but the description adds meaningful behavioral context: it extracts using ONLY the tool result, returns verbatim evidence and confidence, enumerates explicit refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and discloses the extra LLM call cost. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and behavior, then usage guidance and cost. Every sentence contributes: purpose, routing mechanics, return/refusal contract, when-to-use, and trade-off against the sibling. It is information-dense without fluff.

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

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

For a tool with no output schema, the description fully specifies the success and refusal response shapes, enumerates refusal reasons, explains the routing behavior, and clarifies alternatives. Parameters are fully covered by the schema. An agent has everything needed to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters, including the question description and aliases. The tool description adds routing and output context but no additional parameter-level semantics, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads.' It clarifies the grounded behavior—extracting answers only from tool results—and explicitly contrasts with sibling ask_pipeworx ('Same routing as ask_pipeworx'), making the distinction from ask_pipeworx_beta and ask_pipeworx clear without opening schemas.

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: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete domains (financial verdicts, legal claims, medical lookups, public statements). It also gives the alternative and cost trade-off: 'prefer ask_pipeworx for casual lookups' because it costs one extra LLM call.

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?

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), the description discloses important behaviors: auth/paid-tier requirements, parallel tool routing, gap reporting, never-inventing findings, hop fields, contradictions[], semantic excerpting rather than head-truncation, and expected latency. It also explains that citations are only returned when fetchable, which manages the agent's expectations about output reliability.

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 densely packed, and every sentence earns its place: auth, alternative routing, scope, mechanism, return format, best-use cases, depth semantics, citation guarantees, contradiction behavior, and latency. Critical information is front-loaded with the account requirement and fallback tool before the longer functional explanation.

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

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

There is no output schema, but the description fully compensates by describing the return packet structure: verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], hop, citation_uri, and contradictions[]. It also covers error-ish cases like out-of-catalog topics and large-record handling, so an agent has enough context to invoke the tool and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains that depth:'thorough' requires a paid plan, that 'standard' adds gap recovery and contradiction scanning, and that broad/multi-part questions are appropriate because decomposition is the point. This supplements the schema's enum descriptions without being redundant.

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 the tool as grounded multi-source research over Pipeworx's structured data sources, with a specific verb ('research'), resource ('1499 STRUCTURED data sources'), and explicit non-scope ('this is NOT open-web search'). It also differentiates itself from ask_pipeworx and sibling lookup/search tools by emphasizing parallel decomposition and one-call delivery of a findings packet.

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 and when-not-to-use guidance: use it for broad/multi-part structured-data questions, and instead use ask_pipeworx for single lookups or when the topic is not in the structured catalog. It even gives an auth-based alternative ('If you are not signed in, use ask_pipeworx instead'), which is unusually actionable.

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 mark the tool as readOnly, idempotent, and non-destructive, and the description complements this by revealing exact fan-out behavior: SEC EDGAR, XBRL, USPTO, USAspending, Purple Book, DOL LCA, news, and GLEIF. It also discloses important edge-case behavior: empty sections are 'a real no data, not a bug,' and private companies yield resolved:false with an explicit notes line rather than a bare failure. 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 dense and mostly front-loaded: the first sentence states the core purpose and the preferred usage context. The rest is a long list of return fields and edge cases that, while useful, is presented as one large run-on block and could be easier to scan with bullet points. Every sentence does contribute, so no filler.

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

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

Even without an output schema, the description enumerates the return payload in detail: cik, company_name, resolved_from/to, recent_filings with URIs, fundamentals fields, patent/contract/FDA/H-1B/news/LEI sections, and sources_used/sources_failed. It covers input formats, name resolution, private-company behavior, and empty-section semantics, so an agent is fully equipped to invoke the tool and interpret the result.

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, but the description goes beyond the schema by showing accepted value shapes ('AAPL', '0000320193', 'Moderna') and clarifying that type is interchangeable between 'company' and 'ticker'. It also explains resolution behavior for names and the private-company outcome, which the schema does not cover.

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

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

The description opens with a clear statement: 'full cross-source profile of a US public company in ONE parallel call.' It names the resource (US public company), the scope (cross-source), and the delivery mode (parallel call), and then enumerates the specific data domains returned. This distinguishes it from narrow single-source lookups and from sibling tools like resolve_entity, even without naming them explicitly.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' giving a clear condition for selection. It also notes that private companies return resolved:false with notes, which warns against using it for non-public entities. However, it does not name sibling alternatives directly or state when-not-to-use scenarios beyond the holistic-view condition.

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 already cover readOnly and idempotent hints, but the description goes far beyond them: it explains gross-vs-net fee handling, null semantics for temporal_alignment, that compatibility fields can be non-empty even with matched pairs, and that unknown metric_type legs are never paired. This is exemplary disclosure.

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, well-labelled, and front-loaded with the core definition, then modes, then safety fields. However, temporal_alignment_unknown is explained twice in similar terms, and the long code list makes it verbose. Each section earns its place, but some trimming would make it a 5.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It thoroughly documents response structure, top_spreads_pp, flags, skipped counters, fees_note, and the semantics of null temporal_alignment. Nothing an agent needs to interpret results correctly is missing.

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

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

Schema coverage is 100%, so the parameters are already documented. The description adds useful framing about the two modes, that the same token-overlap matcher runs in both, and that explicit tickers override topic-mapped sides. This aids interpretation but does not introduce syntax absent from the schema.

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

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

The description opens with a specific verb-resource pair: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It then distinguishes its two operating modes and clearly separates this cross-venue tool from Polymarket-only siblings like polymarket_arbitrage.

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

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

The description gives clear context for when to use the tool and explains the two modes, including when explicit tickers are preferable to macro shortcuts ('Real cross-venue spreads are rarer than the macro-shortcut list suggests'). It does not explicitly name alternative tools or state when-not-to-use, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, 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?

Annotations already declare readOnly/idempotent, and the description adds substantial behavioral detail: multi-source cascades through EDGAR, GLEIF, OpenFIGI, and RxNorm; ambiguous matches return `figi_candidates`; unresolved identifiers are stated explicitly; enrichment degrades gracefully. This is far beyond what annotations alone provide.

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

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

The description is long and dense, but it is front-loaded with examples and every sentence adds functional value for a complex multi-source resolver. Some subclauses are run-on and would benefit from clearer headings, but there is no filler.

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

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

With no output schema, the description still explains what to expect: labelled identifiers, source provenance, `unresolved` fields, ambiguity via `figi_candidates`, and graceful degradation. It also tells the agent that one call replaces multiple manual lookups, which is important for planning.

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

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

Although schema coverage is 100%, the description adds critical meaning beyond the schema. It specifies acceptable value forms (ticker, CIK, ISIN, brand/generic), explains that a bond must use the issuer name exactly as printed, and describes how ISIN maps to legal entity. This materially improves correct invocation.

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: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It immediately distinguishes the tool from profile, compare, and validation siblings by focusing on ID resolution and giving many concrete query examples.

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 FIRST whenever you have a name but need an ID,' giving strong when-to-use guidance. It also gives type-specific value constraints and warns against passing the full noun phrase. It does not name alternative sibling tools or explicit exclusion cases, but the context is clear enough.

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

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

Annotations already 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.