microlink

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

Annotations already declare readOnlyHint and idempotentHint; the description adds valuable context about the default free model, cost implications of using Anthropic via BYO key, and the exact return structure per model. It also notes that _apiKey is passed straight through, which is a meaningful behavioral detail.

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

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

The description is three sentences, information-dense, with no filler. It front-loads the main action and then logically covers model defaults, return format, and use cases, earning 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 there is no output schema, the description compensates by specifying the per-model return fields (score, confidence, signals, raw_response) and a combined view. It lacks details on how confidence/signals are computed or how errors are handled, but this is acceptable for a read-only, well-annotated probing 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 all four parameters described, so baseline is 3. The description adds extra semantics by explaining the default model option, the BYO key payment implication, and the role of context in disambiguating entities, going beyond the schema.

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

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

The description uses the specific verb 'Probe' and clearly states the resource (business/brand/product/topic) and the output (0-100 visibility score per model). It also differentiates itself from sibling tools by focusing on cross-LLM visibility scoring with concrete use cases like AI-marketing audits.

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 clear context for when to use (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains the default vs BYO key model options. However, it does not explicitly mention when not to use it or compare against similar sibling tools like scan_competitor_ai_presence.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive behavior. The description adds substantial behavioral context beyond those flags: it returns structured answers with stable citation URIs, routes to thousands of verified sources, works across all tiers, and is optimized for speed. This enriches the safety profile with concrete expectations without contradicting annotations.

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

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

The description is long but intentionally dense, front-loading the most critical directive ('PREFER OVER WEB SEARCH') and then layering context. Every sentence carries value: use cases, examples, alternatives, and behavioral notes. While slightly verbose, it earns its length given the need to differentiate from six sibling tools, and the structure is scannable.

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

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

Given the tool's complexity as a routing agent and the absence of an output schema, the description covers all essential aspects: when to use, what it returns (structured answers with pipeworx:// citations), specific exemplified queries, and fallback strategies. No critical context seems missing for an agent 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?

The input schema provides 100% coverage of the single required parameter with aliases (question, query, q, prompt, text, input) and a clear description. The tool description itself does not elaborately explain parameter semantics beyond the schema's examples, relying on the schema's natural-language definition. Baseline 3 is appropriate since the schema handles the burden effectively.

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 routes natural-language questions to the appropriate tool and returns structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by noting its role as the default entry point and coverage of 5,529 tools across 1,455 sources, making the tool's purpose unmistakable.

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

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

Guidelines are exceptionally explicit: 'PREFER OVER WEB SEARCH' and 'START HERE' establish primary use, while 'Step up only when needed' names exact alternatives (grounded for hallucination-resistant answers, deep_research for broad multi-part questions). It also clarifies when breaking-news requests are covered, providing both when-to-use and when-not-to-use 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?

Beyond the annotations (readOnly, idempotent, etc.), the description adds valuable behavioral context: it is an experimental edge, may have candidate routing improvements enabled, and currently matches ask_pipeworx exactly. It also clarifies it's a full working router, not a fallback stub, which is useful transparency.

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

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

The description is a compact paragraph with four sentences, each adding relevant information: beta status, identical behavior, current state, usage direction, and experimental nature. No wasted words, though it could be slightly more concise for extreme efficiency.

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 absence of an output schema, the description adequately mentions the response shape ('same response shape'), experimental edge, and that it's a full working router. It provides enough context for an agent to decide when and how to invoke it, though it doesn't detail return values beyond the reference to ask_pipeworx.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for 'question'. The description does not add parameter-specific semantics, but it doesn't need to since the schema already fully explains them. Baseline of 3 is appropriate.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, an identical universal router with the same tool set, arguments, and response shape. It also distinguishes itself from the stable sibling by noting the experimental routing improvements and current inactive candidate.

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

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

Explicitly instructs to 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It also notes the current state (no active candidate) so users know it matches ask_pipeworx exactly right now.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses the full internal process: routing through 5,529 tools, filling arguments, fetching data, and extracting the answer only from the tool result. It details the return shape and refusal reasons, and reveals 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 dense but every sentence earns its place: value proposition, process, return format, refusal cases, usage guidance, and cost tradeoff. It is front-loaded with the key differentiator and remains highly 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?

Since there is no output schema, the description fully explains both success and refusal response structures. It covers the extra cost, when to use the alternative, and the behavioral constraints, making it complete for a complex tool with rich annotations.

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

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

The schema has 100% description coverage for all 6 parameters, which are aliases for 'question'. The description does not add parameter-level meaning beyond the schema; the baseline 3 applies because the schema carries the 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 clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' and differentiates it from the sibling ask_pipeworx by explaining the extraction behavior and the extra LLM call cost. The verb+resource is specific and it immediately distinguishes itself from the regular ask_pipeworx.

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

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

It explicitly states when to use this tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also provides an exclusion: 'prefer ask_pipeworx for casual lookups,' naming the alternative and giving clear decision guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description goes far beyond them by disclosing fan-out behavior, resolver confidence levels, blocking statuses (low_confidence_match, market_closed_or_inactive), liquidity warnings, cancellation-rule risk, and news fallback mechanics. This is exceptionally rich behavioral context.

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

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

The description is long but highly structured with all-caps section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY) that make it scannable. Every paragraph carries a distinct, useful behavioral fact; it's dense rather than padded, though a slightly shorter version could exist without losing critical information.

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

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

With no output schema, the description fully specifies the response envelope: market fields, analysis fields, evidence keys, parent_event structure, news fields, statuses, and cancellation-rule semantics. It covers blocking routes, edge cases, and when to distrust the analysis, making the tool nearly self-documenting.

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 each parameter already has a clear description and examples. The tool description reinforces the accept-any-input-format behavior but doesn't add new parameter-level semantics beyond what the schema provides; the value it adds is about fan-out behavior and response shapes, not parameter details.

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

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

The description opens with a specific verb+resource ('Research a Polymarket bet by pulling the relevant Pipeworx data') and clearly differentiates itself from siblings like polymarket_edges and validate_claim by positioning itself as a one-call data-pull research tool. It also names concrete user intents ('should I bet on X', 'is there edge in Z'), making its purpose unmistakable.

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

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

The description explicitly states 'Use for' with three query phrasings, giving clear context for when to invoke the tool. It does not explicitly name alternative tools to avoid, but the use-case framing effectively distinguishes it from trade/arbitrage-focused sibling tools.

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

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

Annotations already declare the tool read-only, open-world, idempotent, and non-destructive, so the description adds rich behavioral context beyond those hints. It details data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handles off-calendar fiscal years correctly (AAPL Sep, NVDA Jan), explains result sorting by primary metric, and mentions paired data with citation URIs. No contradictions with annotations.

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

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

Although the description is longer than typical, every sentence earns its place: trigger examples, preference over alternatives, data source details, sorting behavior, and return format are all packed densely. It is front-loaded with user intents and ends with functional benefits. No filler or repetition with the schema.

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

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

For a tool with only two parameters and no output schema, the description is remarkably complete. It covers both entity types, input formats, data provenance, fiscal-year nuances, sorting, and output structure (paired data + citation URIs). This gives an agent sufficient context to invoke the tool correctly and set expectations for results, 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 coverage is 100%, so the baseline is 3. The description adds value by providing concrete examples ('AAPL','MSFT' vs 'ozempic','mounjaro') and explaining type-specific requirements (tickers/CIKs vs drug names) beyond the schema's concise descriptions. It also clarifies behavior tied to parameters (off-calendar fiscal year handling) but does not introduce entirely new semantics, hence a 4 rather than 5.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single parallel call. It specifies the verb "compare" and the resource (entities), and distinguishes from sibling tools by emphasizing it should replace sequential single-pack lookups. Trigger phrases like 'X vs Y' and 'which is bigger' make the intent unmistakable.

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

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

Usage guidance is explicit: it lists exact user phrasings that should trigger this tool ('Compare X and Y', 'X versus Y', etc.) and states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also clarifies when to use type='company' vs type='drug', providing clear decision criteria relative to alternative 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?

Beyond the readOnly/idempotent annotations, the description discloses the parallel tool routing, gaps[] handling (never invented), contradictions[] scan, citation_uri resolvability, semantic excerpting of large records, and expected latency range. This adds substantial behavioral context beyond annotations.

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

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

The description is long but information-dense, with every sentence adding operational details (account tier, source types, fallback, depth semantics, gap recovery, latency). It could be slightly trimmed without losing value, but the structure flows logically from prerequisites to usage to behavior.

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 parameters, and rich annotations, the description covers prerequisites, use cases, alternatives, behavioral nuances, and performance expectations. No critical missing information was found; it is complete for an agent to select and invoke correctly.

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

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

The schema already covers both parameters (question and depth) with descriptions and enum values. The description adds practical selection guidance for depth levels and clarifies that broad/multi-part questions are fine for the question parameter, supplementing the schema meaningfully.

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

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

The description clearly states the tool performs grounded multi-source research across Pipeworx's 1455 structured data sources in one call, decomposing questions into facets and routing them in parallel. It distinguishes itself from siblings like ask_pipeworx by explicitly noting it is NOT open-web search and listing when to use it for broad/multi-part questions.

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 contrasts with ask_pipeworx for single lookups and breaking/current-news topics, advising when to prefer the alternative. It also explains depth levels and when to use each, plus notes account requirements and fallback options.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavior: it returns top-N tools with names, descriptions, full schemas, and curated examples, and eliminates the need for a second schema lookup. This goes beyond annotations and helps the agent predict output structure.

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 then provides a detailed list of domains, return format, and when to use. It is somewhat long due to the domain enumeration, but every sentence contributes useful information. It earns a 4 for being well-organized and purposeful, though not maximally 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 discovery tool with no output schema, the description adequately explains what will be returned (names, descriptions, schemas, examples) and when to invoke it. The annotations cover safety and idempotency. Given the low complexity and rich schema, the description is complete enough for an agent to select and call 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 description coverage is 100%, with all parameters (including aliases) documented in the schema. The description mentions 'top-N' which relates to the limit parameter, but it does not add specific meaning beyond what the schema already provides. Per the rubric, baseline 3 is appropriate when schema fully covers parameter 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 uses a specific verb ('Find tools') and resource ('tools') plus the mechanism ('by describing the data or task'). It clearly distinguishes itself from sibling tools by stating it returns a list of relevant tools with schemas ready to call, and explicitly says 'Call this FIRST' when many tools are available. This is a distinctive meta-purpose.

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

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

The description explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' However, it does not name specific alternative tools or explicitly state when NOT to use it, so it stops short of a full 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 read-only, idempotent, and open-world, but the description adds more: parallel fan-out across sources, specific return structure, USPTO API sunset soft-fail, and GDELT→GNews fallback. This gives the agent a richer model of the tool's behavior beyond the annotations.

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

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

The description is a single long paragraph but every clause conveys necessary information: examples, alternative guidance, fan-out behavior, and return fields. It is front-loaded with user-phrase triggers, making it skimmable, though it could benefit from slight segmentation.

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

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

With no output schema, the description fully compensates by enumerating the exact return payload (cik, filings, fundamentals, patents, news, LEI) and explaining edge cases like patents soft-fail and name resolution. It sufficiently covers the tool's complexity and usage constraints.

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 already covers 100% of parameters with descriptions, including the type enum and value format. The description reinforces with concrete examples ('AAPL', '0000320193') and reiterates the constraint that names are not supported, but adds minimal semantic nuance beyond the schema.

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

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

The description states 'full cross-source profile of a US public company' with concrete example queries like 'Tell me about X'. It names specific outputs (CIK, filings, fundamentals, patents, news, LEI) and explicitly differentiates itself from chaining single-pack lookups, making its purpose unmistakable.

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

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

It provides explicit when-to-use signals ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups') and gives an alternative for unsupported inputs ('use resolve_entity first if you only have a name'). The examples of user intents clarify the expected trigger scenarios.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description only needs to add context beyond that. It adds usage context (stale context, sensitive data) but does not disclose additional behavioral traits like error handling or irreversibility. This is adequate given annotation coverage, but not rich.

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

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

Three sentences, front-loaded with the action, no wasted words. Each sentence adds value: action, usage scenarios, and sibling pairing. Perfectly concise structure.

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

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

For a simple one-parameter delete tool with no output schema and good annotations, the description is complete. It covers what the tool does, when to use it, and how it relates to siblings. Nothing essential is missing.

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

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

Schema description coverage is 100% (the 'key' parameter is described as 'Memory key to delete'). The description reinforces 'by key' but adds no additional 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 uses the specific verb 'Delete' with a clear resource ('a previously stored memory') and mechanism ('by key'). It clearly distinguishes from siblings like 'remember' (store) and 'recall' (retrieve), making the tool's purpose unambiguous.

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

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

Explicitly states when to use the tool ('when context is stale, the task is done, or you want to clear sensitive data') and mentions pairing with 'remember and recall,' providing clear guidance on when this tool is appropriate versus alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it fetches the page, extracts title/description/key links, emits standard llms.txt markdown, and outputs a single text blob. No contradiction with annotations.

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

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

The description is front-loaded with the main purpose, then explains the process and output, followed by a concise use-case list. Every sentence adds value with no wasted words or redundancy.

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

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

Given the tool's simplicity (2 params, no output schema, strong annotations), the description is complete. It explains the output format ('single text blob ready to drop at site-root/llms.txt') and the behavioral process, covering all necessary context for an agent to decide usage.

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

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

The input schema already provides full descriptions for both parameters (url and max_links), covering 100%. The description reinforces that the tool works for 'any URL' but does not add semantic detail beyond what the schema provides, warranting the baseline score.

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 generates a 'production-ready llms.txt file for any URL' using a specific verb and resource. It distinguishes itself from sibling tools by focusing on the llms.txt output format and AI crawler indexing, making it 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 three explicit use cases ('Useful for: 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'), giving clear context for when to use it. However, it does not mention any exclusions or alternative tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds useful behavioral context by listing the exact return fields (title, description, image, author, publisher, logo, structured data) and implies no page rendering. 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 short sentences, front-loaded with the action, and every part adds value: purpose, output details, and use case. 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?

For a simple one-parameter tool with annotations covering safety and an output schema present, the description covers purpose, output fields, and when to use it. Nothing critical is missing.

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

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

Schema has 100% coverage for the single 'url' parameter, and the description does not add additional meaning beyond what the schema provides. The baseline of 3 applies, as the description adds no extra parameter 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's function with a specific verb ('Extract metadata') and resource ('from any URL'), and distinguishes it from siblings by listing output fields (title, description, image, etc.) and purpose ('preview page content'). No ambiguity.

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 clear usage context: 'useful when you need to understand a webpage without visiting it directly.' However, it does not explicitly mention alternatives or when not to use the tool, so it falls short of a 5.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, which the description does not contradict. The description adds value by specifying that it lists only the caller's subscriptions (scope), that it returns specific fields (id, type, params, etc.), and that it shows active subscriptions by default. This goes beyond the annotation basics.

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

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

The description is only three sentences: the purpose, the return fields, and the usage guidance. It is front-loaded with the action, provides essential details, and has no unnecessary words.

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

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

Given the tool's simplicity (one optional parameter) and strong annotations, the description is complete. It covers what it does, what it returns (listing fields explicitly), and when to use it. Without an output schema, the explicit return field list is especially helpful.

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

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

The schema fully describes the only parameter, 'include_inactive', with a clear description and default value. The tool description does not add additional parameter semantics, but with 100% schema coverage, a baseline of 3 is appropriate.

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

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

The description uses a specific verb 'List' and identifies the resource as 'the caller's active subscriptions,' clearly stating the operation and scope. It also distinguishes from sibling subscribe/unsubscribe tools by framing the use case as 'review what you're monitoring before adding more or to find an id to cancel.'

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

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

The description explicitly states when to use this tool: 'before adding more subscriptions' and 'to find an id to cancel.' This implies that for adding or cancelling you would use subscribe/unsubscribe, providing clear guidance and implicit alternatives.

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

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

Annotations are all false (not read-only, not idempotent, etc.), which gives little safety signal. The description compensates by disclosing important behavior: rate limiting (5/day), quota-free usage, claim_token flow for follow-ups, and that the team reads digests daily. This adds real behavioral context beyond the annotation booleans.

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 longer than necessary but every sentence serves a unique purpose (usage, exclusions, token flow, rate limits). It's front-loaded with the main action and then progressively details edge cases. Could be trimmed slightly without losing value, but not overly verbose 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?

For a feedback tool with 4 params, 1 enum, nested objects, and no output schema, the description covers all critical aspects: what to file, when, when not, exclusions, token mechanism, rate limit, and post-filing follow-up. It even explains the team's review cadence. Nothing important is left unstated.

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 extra meaning around the claim_token usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed'), which goes beyond the schema. It also clarifies the context object's purpose. Minor deduction because the message and type params are already well-documented in the schema.

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

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

Description opens with a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly enumerates feedback types (bug, feature, data_gap, praise) and differentiates this tool from siblings like ask_pipeworx and pipeworx_trending, which are inquiry/trend tools, not feedback submission.

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

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

Provides explicit when-to-use scenarios: bug, missing tool, praise. Also gives a strong exclusion: do not report issues from other MCP servers, and tells how to identify which server the tool came from. This is exemplary usage guidance with clear boundaries and alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context: data derived from a specific analytics engine, no PII, only (pack, tool, count), and caching behavior varying by window (5min-1h). This goes beyond the annotations and gives the agent insight into data freshness and privacy.

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

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

The description is somewhat long but front-loaded with the core function, followed by a clearly numbered list of use cases and a final sentence on data origin and caching. Each part adds value, though the list could be seen as slightly verbose. Overall it is well-structured and not wasteful.

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

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

For a simple one-parameter tool with rich annotations and no output schema, the description is quite complete. It explains what data is returned, the time windows, use cases, caching, and privacy characteristics. No obvious gaps remain for an agent to invoke it correctly.

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

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

The schema already covers the only parameter (window) with a description and enum values. The tool description adds a minor note that caching duration depends on window, but otherwise does not significantly enhance the parameter meaning. With 100% schema coverage, baseline 3 is appropriate.

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

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

The description clearly states the tool's function: returning top tools, top packs, and total call volume over a recent window (24h/7d/30d). It uses a specific verb ('Returns') and resource ('top tools, top packs, total call volume'), and the title 'Pipeworx Trending' aligns well. It distinguishes from siblings like discover_tools by focusing on current agent usage trends.

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: (1) discovering hot data sources for current events, (2) confirming canonical tool choice, (3) aligning with agent needs. It does not name alternatives or exclusions, but the context is clear enough for an agent to decide when to use this tool. This fits 'clear context, no exclusions'.

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

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds substantial context beyond annotations: explains the partition check threshold (>3pp), semantic anchor Jaccard similarity (≥0.30), placeholder filter (>20% returns null), and the fill check caution that realizable_edge_pp ≤ 0 means the edge is not tradable. 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 long but dense with useful information. It is well-structured with clear sections for each mode and behavioral details, though it could benefit from bullet points to improve scannability. There is no filler—every sentence adds value.

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

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

There is no output schema, but the description explicitly lists response fields for both modes (opportunities[] with gap_pp, suggested_trade, reasoning; partition_check with sum_yes_prices, gap_from_1, placeholders_filtered). It also covers edge cases like skipped_low_similarity and thin_legs, making the tool fully understandable without additional documentation.

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% for both params, but the description adds significant value: provides concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), explains the difference between event and topic modes, and describes the default no-arg behavior. This goes far 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 opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly distinguishes it from sibling tools like polymarket_edges and polymarket_fill_risk, and explains exactly what the tool does.

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

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

Explicit usage guidance is given for each mode: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also provides examples for each parameter and tells the user to use polymarket_fill_risk for custom sizing, naming an alternative.

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

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

Annotations indicate read-only, idempotent, open-world, non-destructive behavior. The description adds rich behavioral context: caching at the KV level for 1 hour, edge calculated net of slippage, Kelly caps at 0.25, model-specific details (halved Kelly for news_momentum, lognormal barriers from 90d FRED log-returns), and diagnostics that reveal why segments may be empty. There is no contradiction with the annotations.

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

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

The description is a single, dense paragraph with embedded all-caps headers and numerous parentheticals, making it a wall of text that is difficult for an agent to scan efficiently. While all information is relevant, it lacks structured lists, separators, or a clear hierarchy, and the length is excessive relative to the tool's complexity. The front-loaded purpose is good, but the rest is not well organized.

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

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

There is no output schema, so the description must fully document return values. It does so thoroughly, describing the top-level response structure (by_segment, fed_candidates/fed_note, _diagnostics with funnel counters) and explaining why a segment might be empty. It also covers caching and the rationale for excluding Fed bets. Given the tool's complexity, this description is exceptionally 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?

While the input schema covers all parameters (100% coverage), the description adds meaningful context beyond the schema. For example, it explains that min_partition_leg_kelly applies specifically to partition legs because basket trades always return kelly_fraction_half=0, and it explains how slippage_pp is subtracted from raw edge before ranking. This strategic explanation is not present in 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 first sentence clearly states the tool's function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This is a specific verb+resource+scope that distinguishes it from siblings like polymarket_arbitrage by framing the use case as 'what should I bet on today' and avoiding the need to page hundreds of markets.

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 ('Built for what should I bet on today — agents discover opportunities...') and includes caveats like excluding Fed bets from ranking due to unreliable signals. It discusses tradeable-edge knobs and diagnostics, but does not explicitly name alternative tools or state when not to use this tool, leaving some ambiguity relative to sibling tools like polymarket_arbitrage.

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 exceeds what annotations provide by disclosing data freshness nuances (snapshots written on cache-miss, gaps mean no scan), the 60-day TTL history depth limit, and that decay is computed on the absolute value of edge_pp_net from daily closes rather than intraday. These are important behavioral traits for interpreting results.

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

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

The description is well-structured with an introduction, a detailed RESPONSE section, and a LIMITS section. Every sentence contributes to understanding the tool's purpose, output, or caveats, and it is front-loaded with the core concept before diving into response structure.

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

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

With no output schema, the description fully compensates by detailing the response fields (tracked[], expired[], snapshot_dates[]) and their semantic meaning. It also covers data accrual, TTL, and decay methodology, making the tool's behavior comprehensible without needing to inspect code or other tools.

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

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

Although schema coverage is 100%, the description adds meaning by explaining the days parameter as a lookback with default 14 and max 30 (aligned with the schema), and window as the snapshot family (24hr|1wk|1mo). It further clarifies that snapshots are written conditionally, aiding interpretation of the days/window interplay.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily polymarket_edges snapshots, answering a specific question about how long an edge has existed and whether it is shrinking. It distinguishes itself from the sibling polymarket_edges by focusing on historical time-series rather than current edges.

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

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

The description provides clear context for when to use the tool, contrasting fresh vs. old edges ('the latter is wide for a reason nobody is willing to take') and explaining the response's purpose. It does not explicitly name alternative tools, but openly states the tool is built from daily snapshots and covers edge persistence, making usage context clear.

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

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

Annotations already state readOnlyHint=true and destructiveHint=false. The description adds significant behavioral context beyond that: it walks the order-book ladder, returns specific fields across modes, interprets size_usd differently (max spend vs target proceeds vs settlement notional), discloses that partial basket fills can strand the user unhedged, and notes the clamp range (10–1,000,000). It also clarifies that one of market/event is required even though the schema marks zero required, which is crucial operational transparency. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place. It is front-loaded with a one-line summary followed by REQUIRES, then clear sections for SINGLE-MARKET and BASKET, and ends with a usage directive. There is no fluff or redundancy; the length is justified by the tool's complexity.

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

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

With no output schema, the description carries the full burden of explaining return values and behavior, and it does so thoroughly: it lists output fields per mode (e.g., top_of_book, vwap_fill_price, slippage_pp, theoretical_sum, realizable_sum, capture_ratio, thin_legs), explains the verdict values, and highlights the key risk of partial basket fills. It also covers parameter defaults and clamping. The tool's complexity is fully addressed.

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, but the description adds substantial meaning: it explains that market and event are mutually exclusive modes, defines side defaults and the 'auto' basket behavior, and clarifies size_usd semantics per mode (buys/spend vs sells/proceeds vs basket settlement notional). This goes well beyond the schema's property descriptions and enables 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 states a specific verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this tool from the sibling tools (polymarket_arbitrage, polymarket_edges) by framing it as a pre-trade risk check rather than a signal generator, and explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.'

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

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

The description explicitly states when to use this tool vs alternatives: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the context (theoretical overround on thin books is not capturable, partial fills convert arbs into unhedged directional positions) and differentiates the two modes (single-market vs basket), providing clear decision guidance.

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

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

Annotations already declare readOnlyHint/idempotentHint, but the description adds extensive behavioral context: it explains the compatibility_warning conditions in detail, describes temporal_alignment's impact on spread validity, and exposes skipped_cross_type/subtype counters to show what comparisons were dropped. It also truthfully discloses that most pre-mapped shortcuts return warnings, which is important expected 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 long but dense and structured. It front-loads the core purpose and then uses labeled sections like 'TWO MODES', 'RESPONSE', and 'SAFETY FIELDS' to organize details. Every sentence adds value, though some could be tightened. Overall it earns its length for a complex tool.

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

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

Given the tool's complexity (3 params, no output schema, no nested objects), the description covers all necessary context: it explains the response structure (leg-by-leg prices, matched spread top_spreads_pp), the meaning of safety fields, edge cases for incompatibility, and temporal alignment. It fully prepares the agent to interpret the tool's output correctly.

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

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

Schema description coverage is 100%, and the description adds meaningful semantics beyond the schema: it explains the two modes, how topic maps to pre-mapped shortcuts, and how explicit tickers override the topic-mapped side. The enum list for topic is also included in the schema and description. The only reason for a 4 rather than 5 is that the schema already documents each parameter's basic purpose.

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+scope: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this from sibling tools like polymarket_arbitrage by focusing on spread comparison, not trade execution, and explicitly limits to same-venue resolving questions.

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

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

The description gives explicit when-to-use guidance: two modes are described (topic shortcuts vs explicit tickers), and it states when the tool is meaningful ('when the bet shapes are equivalent') vs when it warns ('when they aren't the tool says so'). It also provides a critical when-not: 'pre-mapped ≠ tradeable' and warns the user that most pre-mapped topics return compatibility warnings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by disclosing scoping ('Scoped to your identifier') and the dual behavior (retrieve vs list all keys), which is not fully captured by the annotations.

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

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

Two sentences, front-loaded with the primary action, and every sentence contributes meaningful information: usage, examples, scoping, and sibling pairing. No filler or redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description covers the two modes (retrieve/list), scoping, and relationships to remember/forget. It is complete enough for an agent to select and invoke correctly, though a bit more detail on return format could push it to 5.

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

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

The schema covers the 'key' parameter with a description and example, achieving 100% coverage. The description reinforces the omit-to-list behavior already present in the schema but does not introduce new parameter semantics beyond that.

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 action: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This clearly identifies the operation and resource, and it distinguishes itself from sibling tools remember and forget by naming the pairing.

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

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

The description states when to use the tool ('Use to look up context the agent stored earlier...') and explicitly mentions alternatives via 'Pair with remember to save, forget to delete.' It lacks an explicit 'when not to use' statement but provides sufficient 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?

Annotation Contradiction: The annotations declare readOnlyHint=true, but the description explicitly describes a state-changing operation: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This contradicts the read-only hint, making the behavioral disclosure inconsistent and misleading.

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 that efficiently covers purpose, return format, filters, mark_read behavior, and the HTTP alternative. Every sentence carries information, and it is front-loaded with the core purpose. It could be slightly restructured into multiple sentences for readability, but it is not verbose.

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

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

Without an output schema, the description compensates by detailing the event payload (source, citation_uri, raw payload), filter options, mark_read semantics, and an alternative HTTP endpoint. It does not mention pagination or limit behavior beyond the schema, but for a list-like tool with 100% schema coverage, this is sufficiently complete.

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

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

Schema has 100% coverage of parameters with descriptions. The description adds value by explaining purpose and examples for 'type' and 'since', and clarifies the side-effect of 'mark_read'. Limit and unread_only are not elaborated, but they are documented in the schema, so the description supplements rather than repeats.

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

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

The description opens with a clear verb+resource: 'Pull fired events from your subscription feed.' It specifies exactly what the tool does and differentiates it by mentioning the evaluator-persisted feed and optional filters, which distinguishes it from sibling tools like list_subscriptions or recent_changes.

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

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

It says 'Polls work fine' and notes the same feed is available via an HTTP endpoint for scripts, giving practical usage context. It implies when to use this tool (when needing recent alerts from the subscription feed) but doesn't explicitly state exclusions or contrast with alternative tools, so a slight deduction.

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?

While annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds substantial behavioral context beyond these: it fans out to multiple sources in parallel, uses a GDELT→GNews fallback under specific conditions, has a soft-fail for USPTO due to API sunset, and returns structured changes[] grouped by source with citation URIs. This is rich, non-obvious behavior that the annotations alone do not convey.

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 but well-organized: query examples first, then core purpose, then data source details, parameter semantics, return format, and an explicit alternative. Every sentence contributes value. The list of examples is front-loaded to help the agent match user intents. It is longer than average but justified by the tool's complexity, and there is 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?

This tool has no output schema, but the description compensates by stating the return structure (changes[] grouped by source, total_changes count, pipeworx:// citation URIs). It also covers edge cases (fallback sources, rate limiting, API sunset soft-fail, supported entity type) and provides a clear contrast with entity_profile. For a tool that fans out to multiple external APIs, this is a complete and self-contained description.

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

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

The schema already covers all parameters with 100% description coverage, so the baseline is 3. The description goes beyond this by explaining `since` relative shorthand ('7d', '30d', '3m', '1y'), recommending '30d' or '1m' for typical monitoring, clarifying that `value` accepts a ticker or zero-padded CIK, and noting that `type` currently only supports 'company'. This adds meaningful usage nuance beyond the schema.

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

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

The description opens with explicit query examples ('What's new with X', 'latest on Y') and then states the core function: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It clearly identifies the resource (company change feed) and distinguishes from the sibling tool entity_profile by contrasting dynamic change feed vs. static profile.

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

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

The description provides strong usage context via natural language examples and explicitly names an alternative: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also explains fallback behavior (GDELT preferred, GNews when rate-limited or 5xx) and the soft-fail for USPTO, giving the agent concrete guidance on when to expect what.

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

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

Annotations already indicate the operation is non-read-only, idempotent, and non-destructive. The description adds significant context beyond these flags: key-value storage scoped by identifier, and persistence differences between authenticated (persistent) and anonymous (24-hour) sessions. This helps set expectations about data retention and scope without contradicting the annotations.

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

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

The description is three sentences, front-loaded with purpose, followed by usage and storage details. Every sentence adds value, and there is no redundancy or filler. It is concise while covering the essential aspects.

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

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

For a simple save operation, the description covers purpose, when to use, storage behavior, persistence, and companion tools. The input schema fully documents parameters, and annotations cover safety traits, so nothing essential is missing. The absence of an output schema is acceptable since the tool likely returns minimal acknowledgment.

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 well-documented. The description mentions the key-value pair concept and scoping by identifier, which reinforces the relationship between parameters, but it does not add new parameter-level semantics beyond the schema's examples. 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 explicitly states the tool saves data for later reuse, with a specific verb 'Save' and resource 'data... to reuse later'. It clearly distinguishes itself from siblings by referencing recall and forget, which are complementary rather than alternative purposes.

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

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

It provides clear when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples. It also explicitly names alternatives: 'Pair with recall to retrieve later, forget to delete.' This gives the agent decision rules for choosing this tool over siblings.

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

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

The description adds behavioral detail beyond annotations: graceful degradation (LEI/FIGI unavailable but EDGAR returns), explicit unresolved identifiers, source labeling, and internal cascade of lookups. Annotations already declare read-only/idempotent/non-destructive, so this is additional value.

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

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

The description is long but well-structured with example queries up front and a clear 'SUPPORTED TYPES' section. It earns its length with necessary detail, though the company description is dense and could be slightly tightened without losing 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 tool with no output schema, the description comprehensively explains return fields for both entity types, fallback behavior, and how unresolved identifiers are represented. It leaves little ambiguity about what the agent will receive.

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 enriches both parameters: it explains what each entity type returns, gives input examples (ticker, CIK, brand names) and clarifies accepted formats (e.g., 'ozempic', 'metformin'), adding meaning beyond the raw schema.

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

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

The description uses a specific verb ('resolve') with a clear resource (user-spoken NAME to canonical identifiers). It lists concrete outputs (CIK, ticker, LEI, FIGI, RxCUI) and explicitly frames it as the first tool to use when needing an ID, distinguishing it from siblings like entity_profile.

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

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

It states 'Use FIRST whenever you have a name but need an ID,' giving a clear when-to-use. It also explains that it replaces 2-3 manual lookups. However, it doesn't explicitly mention exclusions or alternatives (e.g., when not to use it), so it lacks explicit alternatives.

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

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

Annotations already cover readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds process details (probes each entity, ranks by score, returns ranked list with score/confidence/signal density), which goes beyond annotations and gives the agent a clear behavioral model.

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

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

Two sentences, front-loaded with purpose and mechanism. No redundant details; each sentence adds value (process, use case, 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?

The description covers purpose, process, output format, and use case. It lacks explicit limitations or alternatives, but the schema and annotations fill remaining gaps (e.g., entity count, model options).

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 all parameters have descriptions. The description adds semantic value by clarifying that 'entities' are brand/business/product names and that the first is the subject while others are competitors, reinforcing the narrative role.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, with a specific process: probes each entity via ai_visibility_check, ranks by score, identifies most/least recognized. This distinguishes it from the sibling tool ai_visibility_check, which likely handles single-entity checks.

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

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

Provides an explicit use case for competitive AI-marketing audits with an illustrative question ('does Claude know about us as well as our competitors?'). Does not explicitly state when not to use or name alternatives, 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?

Beyond the read-only/idempotent annotations, the description discloses behavior like partial failure degradation ('sources_failed will list it if it times out'), the 5-30s first-measurement delay for bundlephobia, and the exact return shape. This gives agents realistic expectations for latency and error handling.

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

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

The description is dense but not verbose; every sentence adds value: purpose, usage, output fields, ecosystem scope, and failure behavior. It's appropriately sized for a composite tool and front-loaded with the primary 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?

The absence of an output schema is compensated by listing all return fields explicitly. The description covers return values, error handling, timing, and ecosystem limitations, making it complete for a read-only npm dependency evaluation tool.

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

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

The input schema already provides full descriptions for both parameters (package name and version). The description adds minimal additional parameter-specific semantics but reinforces the default behavior (latest version) without contradicting the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose as a composite npm package evaluation check, enumerating specific data sources (deps.dev and bundlephobia) and the aspects it covers (license, advisories, version history, bundle size, dependency count, ESM/tree-shake support). This makes it highly distinguishable from sibling tools.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also specifies ecosystem limits ('NPM ecosystem only in v1') and directs other ecosystems to deps.dev:version directly, providing clear exclusions.

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

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

The description discloses non-obvious behavior beyond annotations: the embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, input cap of 200K chars with truncation and flagging, and that passages include character offsets for verification. These are valuable behavioral details not derivable from the readOnly/idempotent annotations.

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

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

The description is a single dense paragraph with no filler; it front-loads the core purpose and ends with technical constraints. While slightly long, each sentence contributes value—usage guidance, pairing with a sibling, and output details—so it's appropriately concise for the tool's complexity.

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

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

Even without an output schema, the description explains the return format (top-N passages with character offsets and similarity scores), operational constraints (truncation at 200K chars), and integration option with ask_pipeworx_grounded. This covers all essential aspects for an agent to invoke and 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 description coverage is 100% with clear parameter definitions. The description adds practical examples (SEC 10-K, article) but no parameter-specific meaning that isn't already in the schema. Per the rubric, the baseline for high schema coverage is 3, and the description doesn't elevate beyond that.

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

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

The description explicitly states 'Semantic search INSIDE a fetched record' with a specific verb and resource, and distinguishes from siblings by referencing ask_pipeworx_grounded as an alternative. The title 'Search Within a Source' aligns, making the tool's purpose immediately clear.

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

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

It provides explicit guidance: 'Use when the record is too big to cram into the prompt' and 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This clearly contrasts with alternatives and defines the ideal usage 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?

Beyond annotations, the description discloses important behavioral traits: auth requirements, delivery channel behaviors (email templated, SMS phone verified with 10/day cap, webhook HMAC signing and auto-disable after 10 failures), and the always-on feed. These details go far beyond the annotations and give the agent critical side-effect knowledge. No contradictions with annotations.

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

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

The description is a single dense paragraph, but every clause contributes value. It covers purpose, auth, types, delivery, verification, and caps in an organized flow. While not broken into bullets, the information density is justified given the tool's complexity. Slightly long but 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?

Given the tool has nested objects, no output schema, and multiple subscription types, the description covers all necessary context: return value, delivery channels, parameters for each type, prerequisites, and error-prone details like phone verification and webhook signing. It is thorough enough for an agent to invoke correctly without additional documentation.

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

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

Schema coverage is 100%, but the description significantly enriches parameter meaning. It provides concrete examples for each type (e.g., sec_8k with items, polymarket_edge with topic, fred_series with series_id) and explains delivery parameter semantics (email/sms/webhook details, verification, signing secret). This exceeds the baseline expected from schema coverage.

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

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

The description clearly states the tool's function: 'Create a proactive monitoring subscription to a live-data event stream' and notes it 'Returns the new subscription id.' It lists supported types and delivery channels, making the purpose and scope unambiguous. This distinguishes it from siblings like list_subscriptions and unsubscribe.

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

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

The description gives clear context on when to use the tool (to create subscriptions) and prerequisites (requires Pipeworx OAuth, anonymous/BYO cannot persist). It also explains how feeds are consumed via recent_alerts or a GET URL, implying the workflow. However, it does not explicitly contrast with alternative tools like unsubscribe or list_subscriptions, so it lacks explicit when-not 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, openWorld, idempotent, and non-destructive. The description adds valuable context beyond annotations by detailing what the returned data contains (category buckets, exact tool + argument shape, live catalog) and the intended onboarding use case. No contradictions. It does not discuss edge cases or limitations, but with strong annotations the bar is met.

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

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

The description is longer than two sentences but is well-structured: it opens with example user queries, states the purpose, describes the return format, and ends with usage guidance. Each sentence adds value, and the key 'Use this FIRST' guidance is prominent. Slightly verbose with the long list of topic categories, but appropriate for an onboarding 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?

This is a low-complexity tool with one optional parameter and no output schema. The description covers the return value (category-bucketed questions with tool shapes), the parameter behavior (omit vs topic), and the exact situations for use. It is complete enough for an agent to invoke correctly without further documentation.

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 only repeats the topic examples ('finance', 'pharma', 'betting') already listed in the schema description, adding no new semantic information about format, default behavior, or constraints. It confirms the 'focus' behavior but does not go 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 identifies the tool as the onboarding entry point, with a specific verb+resource ('returns category-bucketed example questions') and distinguishes it from siblings by positioning it as the first call when unfamiliar with Pipeworx. It is far more specific than the title 'What Can I Ask Pipeworx?' and explains the exact output (example questions with tool + argument shapes).

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, or to learn how to call the meta-tools', giving clear when-to-use guidance. It also explains the no-arg vs topic parameter usage. However, it does not explicitly name alternative tools or state when not to use it, 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=false, so the safety profile is clear. The description adds valuable context beyond annotations by specifying the return format (image URL) and the nature of content (rendered page layout and visual content), helping the agent understand what to expect.

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

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

The description is a single, well-structured sentence that front-loads the action and includes all necessary details without any fluff. Every clause contributes meaning.

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

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

For a simple, read-only tool with one parameter, complete annotations, and an output schema, the description covers purpose, return value, and use case. It is fully sufficient for an agent to select and invoke the tool correctly.

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

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

The schema provides 100% coverage for the single 'url' parameter with a clear description. The tool description does not add significant detail beyond the schema, but it reinforces the 'any webpage' scope. Since the schema does the heavy lifting, a baseline of 3 is appropriate.

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

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

The description clearly states the specific action ('Capture a screenshot'), the resource ('any webpage'), and the return value ('image URL showing the rendered page layout and visual content'). It is unambiguous and distinct from any sibling tools, none of which relate to screenshots.

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

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

Provides a clear use case: 'use to verify page state or design.' It does not mention explicit alternatives or exclusions, but none are needed given the absence of similar sibling tools. The context is sufficiently clear to know when to invoke it.

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

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

Beyond the annotations, the description discloses that the row is deactivated rather than deleted, and that historical events remain available via recent_alerts. It also states ownership enforcement, which is a meaningful behavioral constraint not captured in 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 front-load the core action and are followed by a brief ownership note and a clarity about the deactivation behavior. Every sentence earns its place with 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 single-parameter mutation tool with no output schema, the description covers the essential context: what happens (cancellation/deactivation), the ownership constraint, and the impact on historical alerts. The annotations further cover safety and idempotency, making this 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?

The input schema fully documents the 'id' parameter, including its type and provenance ('returned by subscribe'). The description does not add additional parameter semantics beyond saying 'by id,' so it adds no extra value over 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 and resource: 'Cancel a subscription by id.' This clearly identifies the tool's action and scope, and it distinguishes from sibling tools like list_subscriptions and subscribe by focusing on cancellation.

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 usage context by noting ownership enforcement ('you can only cancel your own subscriptions') and the deactivation behavior. However, it does not explicitly state when to choose this over alternatives, leaving the 'when to use' somewhat implicit.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds crucial behavioral context: the two processing paths, the verdict set, the citation format, and the explicit warning that could_not_verify means the check didn't happen and must not be treated as evidence. There is no contradiction with annotations.

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

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

The description is dense and well-organized: query triggers, purpose, usage, routing, return value, and an important caveat. Every sentence contributes meaningful information, and the formatting with bullets and a highlighted 'IMPORTANT' note improves scanability. It is appropriately sized for the tool's complexity.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: lists the possible verdicts, mentions actual value with citation and reasoning, and clarifies the two ambiguous verdicts (could_not_verify and unsupported). It also explains the high-level internal routing, making the tool's behavior predictable for callers.

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?

Since schema description coverage is 100%, the baseline is 3. The description does not substantially add to the parameter documentation; it only references the claim and tolerance concept in passing. The examples in the schema already capture the meaning of both parameters, so the description neither improves nor harms.

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 explicit natural-language triggers and states 'natural-language claim verification against authoritative sources' — a specific verb+resource. It clearly distinguishes the tool from siblings by defining its scope (verifying factual claims, with a special fast path for company-financial claims) and by noting it replaces 4–6 sequential calls.

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

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

It gives explicit usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing between the SEC EDGAR/XBRL fast path and the grounded pipeline, and clarifies handling of special verdicts like could_not_verify, which helps avoid misuse.

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