iconify

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

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond this: the default model is free, passing _apiKey probes Anthropic with the user paying directly, and it discloses the return format (per-model score, confidence, signals, raw_response + combined view). This gives the agent a clear picture of cost and external call behavior.

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

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

Three sentences, each with a clear purpose: main action, model/cost defaults, return format and use cases. It is front-loaded with the core verb, contains zero filler, and every clause earns its place. Perfectly sized for quick comprehension.

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 fully discloses the return structure (per-model {score, confidence, signals, raw_response} + combined view). It also covers the only param that needs extra explanation (_apiKey cost), default behavior, and use cases, making the tool's behavior predictable and complete.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description adds meaningful semantic value by explaining that 'workers-ai' is the free default and that providing _apiKey incurs Anthropic costs, which directly informs parameter choices beyond the schema's own descriptions. This elevates it slightly above baseline.

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

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

The description opens with a specific verb and resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly distinguishes it from sibling tools like ask_pipeworx or deep_research, and the stated use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) further clarify its niche.

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

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

The description gives explicit context for when to use the tool ('Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring'), which serves as clear usage guidance. It does not explicitly name alternatives or exclusions, but the use-case framing is enough to differentiate it from similar siblings 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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds that it routes to thousands of tools, fills arguments, and returns cstationed structured answers with stable URIs — useful behavioral context beyond the annotations. It does not cover error handling, failure modes, or source-availability limits, so it is not a perfect 5.

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 key guidance is front-loaded and the examples are helpful, but the description is wordy and contains a garbled run-on transition about ask_pipeworx_grounded and deep_research. The long domain list and repeated 'use whenever' guidance could be tightened.

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

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

For a complex routing tool with no output schema, the description covers the return shape, citation behavior, authority, and alternatives. It is sufficient for an agent to select and call it; only edge-case behavior such as no-match questions or ambiguous inputs is left unsaid, which is a minor gap given the 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?

Schema coverage is 100%: all six parameters are clearly documented as question aliases. The tool-level description gives natural-language examples but adds little parameter meaning beyond what the input schema already provides, so the baseline 3 applies.

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

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

The description is specific: it says ask_pipeworx swaps web search for factual questions, routes to 5,767 tools across 1,506 verified sources, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It also distinguishes itself from alternatives like ask_pipeworx_grounded and deep_research, so the tool’s role is 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 explicitly says 'PREFER OVER WEB SEARCH', lists concrete trigger phrases and topics, gives examples, and names when to use ask_pipeworx_grounded for well-scoped single facts and deep_research for broad/multi-part questions. This is strong routing 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?

The description adds meaningful behavioral context beyond the annotations: it is an experimental edge, candidate routing improvements are live only when under test, and it falls back to nothing—it is a full working router. This clarifies operational expectations that readOnlyHint and idempotentHint 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?

Every sentence is load-bearing: beta identity, current candidate state, usage instruction, stable comparison, and no-fallback clarification. It front-loads the core identity and keeps caveats later in the paragraph, 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 tool with no output schema, the description covers what it does, its current operational state, how to invoke it, and what it is not. Response shape is deferred to ask_pipeworx, which is appropriate because the tool is explicitly identical to that stable sibling. Annotations cover the read-only and idempotent safety profile, leaving nothing critical missing.

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

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

Schema description coverage is 100%, with the question parameter and all aliases (q, text, input, prompt) fully documented, so the description does not need to repeat them. The tool description only mentions 'same arguments' as ask_pipeworx, adding no new parameter semantics, so the baseline 3 applies.

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

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

The description clearly identifies this as the beta variant of ask_pipeworx, a universal router with the same 5,767 tools and same response shape, and explicitly contrasts it with the stable sibling. This gives the agent a concrete verb+resource identity and distinguishes it from ask_pipeworx and ask_pipeworx_grounded.

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 instructs the agent to 'Use it exactly like ask_pipeworx' and provides the selection condition: use it when you want the newest routing. It also clarifies the current state (no candidate active) so the agent knows this currently behaves identically to the stable router.

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

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

Annotations already mark this read-only, open-world, idempotent, and non-destructive; the description adds substantial beyond that: exact return shape, verbatim evidence, refusal reasons, possible data-truncation, and the extra LLM cost versus the sibling tool. Nothing contradicts 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 dense but information-rich; every sentence adds a distinct fact about mode, return shape, refusal behavior, or cost trade-off. The refusal-reason list is long but operationally useful, so the slight length is justified.

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 fully specifies the success return shape and the explicit refusal cases with reasons. It also covers cost, grounding constraint, and when the agent should prefer a different tool, leaving no ambiguity about how to call or interpret this 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 six parameters documented, so the description does not need to explain them individually. It adds minor context about the tool filling arguments during routing, but the parameter semantics themselves are already fully covered by the schema.

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

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

The description clearly states it is a hallucination-resistant grounded answer mode for high-stakes reads, and explains it routes like ask_pipeworx then extracts only from tool results. This gives a specific verb, resource, and behavior, and distinguishes it from the sibling ask_pipeworx and ask_pipeworx_beta.

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 criteria ('when an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when-not-to-use guidance ('prefer ask_pipeworx for casual lookups'). It also names the alternative tool and explains the trade-off (one extra LLM call).

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

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

Even with annotations (readOnlyHint=true, etc.), the description adds substantial behavioral detail: resolver contract with confidence levels, parent_event extractor, news fallback behavior, low-confidence short-circuit, closed-market status, illiquid spread handling, and cancellation-rule risk. It also cautions agents to inspect resolver fields before trusting analysis, which is critical behavior 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 effectively structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). The core purpose is front-loaded in the first two sentences. While every section provides actionable info, the sheer length prevents a perfect score for conciseness; it is dense but necessary 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?

Given no output schema, the description thoroughly covers return values (result.market, result.analysis, result.evidence, result.parent_event) and edge cases (low_confidence_match, market_closed_or_inactive, illiquid_wide_spread). It also explains safety mechanisms and resolution-rule risks, making it complete for an agent to use 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?

The schema already covers all parameters with descriptions (100% coverage), so baseline is 3. The description adds extra meaning by illustrating how 'depth' affects fan-out with specific examples (e.g., 'BTC bet → coingecko + fred + gdelt+gnews') and by detailing what 'include_raw' returns. This goes beyond the schema's simple descriptions, so a 4 is warranted.

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's core function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' and then details the output (evidence packet + market-vs-model comparison). It distinguishes itself from siblings by focusing specifically on Polymarket bets with Pipeworx data, and includes concrete use cases like 'should I bet on X', making it highly specific.

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 usage context: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' and explains input formats (slug, URL, question text). However, it does not explicitly name alternative tools or scenarios where the tool should NOT be used, 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?

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds substantial behavioral context: data sources (SEC EDGAR/XBRL, FAERS), fiscal-year handling (e.g., AAPL Sep, NVDA Jan), sorted results by primary metric, and return format (paired data + pipeworx:// citation URIs). This fully discloses what happens during execution 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 dense but every sentence serves a purpose: trigger phrases, scope limits, data sources, sorting, return format, and efficiency gain. It is front-loaded with the most important usage cues and avoids redundancy. Slightly long, but for a tool that replaces many sequential lookups, this detail is justified.

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 correctly explains return values ('paired data + citation URIs') and behavioral guarantees (sorted results, fiscal-year correctness). It covers types, examples, size limits, and alternatives, making it complete for a complex comparison tool. No significant gaps remain.

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

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

Although the input schema has 100% coverage with descriptions for both 'type' and 'values', the description enriches parameter meaning by specifying what each type returns: 'type="company" pulls LATEST 10-K revenue...' and 'type="drug" pulls FAERS adverse-event counts...' It also clarifies output sorting behavior, adding value beyond the schema's basic constraints.

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: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It enumerates trigger phrases like 'X vs Y' and 'rank these companies,' and distinguishes itself from single-entity lookups by noting it 'Replaces 8–15 sequential lookups.' This is a specific verb+resource with clear sibling differentiation.

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

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

Usage guidance is explicit: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It defines when to use the tool (comparison, ranking, head-to-head queries) and provides conditional data specifics for company vs. drug types. This goes beyond implied usage and gives clear direction on prioritizing this tool.

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

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

Annotations already mark it read-only, idempotent, and non-destructive; the description adds substantial behavior beyond that: account/plan requirements, latency estimates, gap[] handling, never-invented evidence, resolvable citation_uri, semantic excerpting, and contradictions scan. No annotation contradiction.

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

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

The description is long but front-loaded with the account gate and each clause carries useful behavior or routing information. It is dense rather than redundant; minor partial overlap with the schema's depth enum details keeps it from a 5.

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

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

No output schema exists, so the description carries the full burden of explaining return values; it does so in detail: verbatim evidence, confidence, source, fetched_at, citations, gaps[], hop, and contradictions[]. Auth, latency, input type, depth options, and sibling routing are all covered, leaving little for an agent to guess.

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

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

Schema coverage is 100%, but the description adds meaning beyond schema by explaining that 'thorough' requires a paid plan, that standard/thorough add gap-recovery and contradiction scans, and by attaching latency expectations to depth choices. It also frames 'question' as natural-language and broad/multi-part friendly.

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?

States a specific verb and resource: multi-source grounded research across Pipeworx's structured data sources in one call, producing a findings packet. It clearly distinguishes itself from open-web search and from the single-lookup sibling 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?

Explicitly gives when-to-use guidance: best for broad/multi-part questions over structured data. It also states exclusions: 'For a single lookup use ask_pipeworx instead' and 'If you are not signed in, use ask_pipeworx instead.'

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral context by disclosing the return format: top-N tools with names, descriptions, full schemas, and examples, plus the promise that results are directly callable with no second lookup. This goes beyond the annotations.

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

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

The description is well-structured and front-loaded with purpose. It includes a useful list of domains to illustrate scope, though this list is somewhat lengthy. Each sentence contributes value: purpose, scope, output details, and usage guidance.

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 explains what it returns (top-N tools with schemas and examples) and when to invoke it ('Call this FIRST'). It does not discuss error cases or what happens if no tools match, but for a discovery tool the essential context is covered.

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

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

Schema coverage is 100%, with detailed descriptions for the query parameter and its aliases. The tool description only restates that the query is a natural language description and does not add meaning beyond the schema. Baseline of 3 applies due to high schema coverage.

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

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

The description clearly states the tool's purpose with a specific verb+resource: 'Find tools by describing the data or task.' It also explicitly lists the domains it covers and distinguishes itself from siblings as a meta-tool for discovering other tools, not performing domain-specific actions.

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

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

The description gives explicit usage guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It implies when not to use ('not just one answer') but does not name specific alternative tools, so it lacks full alternative naming.

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 establish readOnly, openWorld, idempotent, and non-destructive behavior, and the description goes far beyond them by disclosing fan-out sources, soft-fail behavior for USPTO PatentsView, expected-empty fda_products for non-biologic companies, resolved:false handling for private companies, and the meaning of sources_failed. 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 long, but almost every clause carries behavioral or usage weight, from source fan-out to failure semantics. It is front-loaded with triggers and the preference directive; however, the single-paragraph structure with heavy parentheticals makes it harder to scan than a short bulleted breakdown would be.

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

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

For a complex tool with no output schema, the description covers return sections, source behavior, resolution edge cases, expected empty results, and soft-fail behavior. It provides everything an agent needs to decide when to call it and accurately interpret its results.

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

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

Schema coverage is 100% and the description largely repeats what the schema already states about type and value, including ticker/CIK/name resolution via SEC EDGAR. It adds an output-level note about private companies returning resolved:false, but that is behavioral context rather than new parameter meaning, so it stays at the baseline for fully documented schemas.

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 concrete user phrasings ('Tell me about X', 'research Acme') and states a specific resource: a full cross-source profile of a US public company in a single parallel call. It clearly distinguishes this from chaining individual SEC/XBRL/news lookups and from the broader pool of sibling research tools.

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

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

The description explicitly says to 'ALWAYS PREFER' this tool over chaining single-pack lookups when the user asks for a holistic view, and it gives example triggers. It does not explicitly name sibling alternatives like compare_entities or resolve_entity for cases such as comparison or simple entity resolution, so the exclusion guidance is good but not exhaustive.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true; the description adds context about deleting previously saved memories and the scenario of clearing sensitive data, without contradicting annotations. It does not detail idempotent behavior on missing keys, but that is covered by 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 with action first; includes purpose, usage, and sibling pairing without redundancy. Every sentence earns its place.

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

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

For a single-parameter delete tool with full schema coverage and annotations, the description fully covers what the tool does, when to use it, and its relation to siblings. No output schema is needed for this simple operation.

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

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

Schema covers 100% of parameters with description 'Memory key to delete'; the tool description only echoes 'by key', adding no additional semantic detail beyond schema. Baseline 3 is appropriate since the schema fully documents the parameter.

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' and resource 'previously stored memory by key', clearly distinguishing it from sibling tools like remember and recall. It is unambiguous about the action and target.

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 ('context is stale, task is done, sensitive data') and names complementary tools ('Pair with remember and recall'), giving clear selection guidance 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, idempotent, openWorld, and non-destructive. The description adds useful context about fetching the page, extracting title/description/key links, and emitting a single text blob in standard markdown format.

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

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

Three focused sentences: what it does, how it works, and when to use it. No filler or redundancy, with the most important information front-loaded.

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

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

For a tool with two parameters and no output schema, the description adequately explains expected input, process, and output format. It could mention edge cases like unreachable URLs, but current coverage is sufficient for effective invocation.

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

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

Schema description coverage is 100%, so parameters are fully documented in the schema. The description adds minimal extra semantic meaning beyond restating that the output is a text blob.

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, with a specific verb and resource. It distinguishes itself from sibling tools by explicitly mentioning AI crawlers and the standard llms.txt format.

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 'Useful for' section provides clear use cases: getting a client's site indexed, drafting for own project, or auditing a competitor. However, it does not mention when not to use it or point to an alternative tool.

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

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

Annotations already establish the tool as read-only, idempotent, and non-destructive. The description adds transparency by disclosing the return payload (SVG markup, width, height). It does not conflict with annotations and provides useful behavioral context beyond them.

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

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

The description is extremely concise: two sentences that state the purpose, input format, and output. It is front-loaded with the main action and includes an example, earning its place without any 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 retrieval tool with high schema coverage, an output schema, and comprehensive annotations, the description is complete. It covers input syntax, output contents, and the tool's purpose, leaving no significant gaps given the tool's simplicity.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds extra semantics by explaining the prefix:name format and providing concrete examples, which goes beyond the schema's field descriptions. It reinforces the relationship between prefix and icons.

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: getting SVG code and dimensions for specific icons. It specifies the input format (prefix:name) and distinguishes itself from sibling tools like search_icons by focusing on retrieval of known icons rather than searching.

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 usage context: input icon names in prefix:name format, with examples. It does not explicitly mention exclusions or alternatives, but the specificity of 'for specific icons' implies when to use it. No alternative tools are referenced, so it misses the 'when not to use' guidance but is otherwise clear.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds value by detailing what data is returned and how the output connects to other tools. It does not contradict annotations and adds helpful context about the 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?

Two sentences, front-loaded with the core action, and no filler. Every sentence adds value: the first defines the operation, the second lists outputs and usage guidance.

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 trivial complexity (no params) and the presence of an output schema, the description is complete: it states what the tool returns, the key fields, and how to use them with sibling tools. Nothing more is needed.

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

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

The tool takes zero parameters, so the baseline is 4. The description compensates by explaining the return fields and their purpose, which is sufficient for a parameterless tool.

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 clear action ('Browse available icon collections') with a specific resource and lists the returned fields (prefix, name, icon count, author, license, category). It distinguishes itself from sibling tools by explaining how the prefix will be used with search_icons and get_icons.

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

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

Explicitly tells the agent when to use this tool (to browse collections before using search_icons/get_icons) and names the exact sibling tools that consume the prefix. This provides clear direction and prevents confusion with other list tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the agent knows this is a safe read operation. The description adds minimal behavioral context beyond the annotations—it specifies the return fields and that it lists active subscriptions by default. It does not disclose potential side effects, rate limits, or authorization details, but the annotations lower the burden.

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

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

The description is two sentences, front-loaded with the action and scope. The first sentence states what it does and what it returns; the second gives concrete usage guidance. Every word earns its place, with no redundancy.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers purpose, return fields, and usage context. The sibling tools subscribe and unsubscribe provide additional context, and the annotations cover the safety profile. 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?

The schema covers the only parameter (include_inactive) with 100% coverage, so the baseline is 3. The description adds no additional meaning about the parameter beyond what the schema already states. It implicitly distinguishes active from inactive but does not explain the parameter's syntax or default behavior 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 a specific verb ('List') with a clear resource ('the caller's active subscriptions'), and explicitly states the scope (caller's, active). It also lists the returned fields, making the tool's function unambiguous. This distinguishes it from the sibling tools subscribe and unsubscribe.

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

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

The description provides clear usage context: 'review what you're monitoring before adding more or to find an id to cancel.' This implies when to use the tool relative to subscribe and unsubscribe, though it does not explicitly name these alternatives. It lacks a 'when not to use' clause, but the scenarios are 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?

The description discloses several behavioral traits beyond the annotations: rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), the claim_token return mechanism ('Filing without an account returns a claim_token; pass it back later'), and the team's review cadence ('The team reads digests daily and signal directly affects roadmap'). These details give the agent a complete understanding of side effects and operational constraints, while the annotations only state generic hints (all false).

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

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

The description is comprehensive but not bloated; each sentence serves a purpose. It is front-loaded with the core action, then expands into use cases, exclusions, and specific behavior. The length is justified by the need to convey nuanced routing rules, claim_token workflow, and rate limits. It could be slightly tightened by merging some clauses, but it remains appropriately concise for the complexity of the tool.

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

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

Given the tool's complexity (4 optional params, nested context object, no output schema) and minimal annotations, the description provides all necessary context: what it does, when to use it, what not to do, the claim_token lifecycle, rate limits, and cost. It even clarifies scope confusion ('Not sure? Pipeworx tool names are the ones this connection lists'). This is complete enough for an agent to invoke the tool correctly without guessing.

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 four parameters with descriptions (100% coverage), so the baseline is 3. The description adds meaningful context beyond the schema, especially for claim_token: 'pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed and what changed.' It also provides guidance on how to compose feedback ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), which enriches the semantics of the message and context parameters.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It identifies the resource (Pipeworx tools/packs) and the action (sending feedback), and it implicitly distinguishes from sibling tools like ask_pipeworx or deep_research by focusing on reporting issues, gaps, or praise rather than asking questions or conducting research.

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

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

The description provides explicit when-to-use guidance with concrete examples: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also includes an explicit exclusion and alternative: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server ... file it with that server instead.' This makes the conditions for tool selection unambiguous.

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 read-only/idempotent safety. The description adds meaningful context: it is self-aggregating from CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. 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 first sentence is front-loaded and states the core purpose; bullets organize use cases; trailing sentences add data provenance and caching. No wasted words; every sentence earns its place.

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

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

This is a simple tool with one optional parameter, strong annotations, and no output schema. The description explains return items and data characteristics (pack, tool, count, no PII) sufficiently for an agent, though exact output ordering or limits are unspecified.

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

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

Schema coverage is 100% and the schema description already explains the window enum and tradeoff between short/long windows. The description merely repeats '24h, 7d, or 30d' without adding additional parameter meaning.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume from other AI agents' Pipeworx usage, with a specific verb ('Returns') and scope (recent window). This distinguishes it from siblings like discover_tools by focusing on aggregated trending signal rather than individual tool discovery.

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

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

The description explicitly lists three use cases: discovering hot data sources, confirming a canonical tool before asking, and checking alignment with other agents. It does not name alternative tools or exclusion criteria, but provides clear situational context for when to use this tool.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior, and the description adds substantial behavioral detail: semantic similarity threshold, partition filter with placeholder handling, fill-check pricing against live CLOB depth, and an explicit warning not to trade when realizable_edge_pp ≤ 0. 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 long but well-organized into labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with core purpose. While it could be tightened, every section contributes critical operational knowledge for a complex multi-mode tool, so it earns its length.

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

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

With no output schema, the description explicitly outlines response structure (opportunities[], partition_check fields). It also covers edge cases (placeholder slugs, thin legs, overround only at last-trade), calls out alternative tools, and gives usage examples—comprehensive for the tool's complexity.

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

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

Schema descriptions already cover 100% of parameters, but the description enriches them significantly by explaining how each mode executes (event walks child markets, topic flattens related markets and runs the comparator), what the response contains, and example slugs. It adds meaning beyond the schema's basic field descriptions.

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

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

Description begins with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (no-arg trending scan, event mode, topic mode) and explains what each does, separating it from sibling tools like polymarket_fill_risk.

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

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

Explicit when-to-use guidance: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also explains trade-offs (cross-event catches patterns single-event misses) and points to polymarket_fill_risk for custom sizing, providing clear decision-making context.

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

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

The description goes far beyond the annotations (which already declare read-only, open-world, and idempotent). It discloses caching behavior (KV-level 1h), model family details (lognormal barrier, GDELT ratios, partition overround with per-sport alpha), filtering gates, slippage assumptions, response structure with diagnostics, and limitations (unreliable Fed signals). This is 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 dense and lengthy, but every section earns its place: purpose, model families, response structure, knobs, and caching. It is front-loaded with a one-sentence purpose and uses capitalized headers for scannability. A slight deduction because some details (e.g., exact alpha values, funnel counters) could be considered excessively specific for a tool description, but overall well-structured.

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

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

Given the tool's complexity (9 parameters, multiple model families, no output schema), the description covers all needed context: what the tool does, how opportunities are segmented, what response fields to expect, how to tune filters, why certain segments may be empty (diagnostics), and known limitations. It is complete enough 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?

Schema coverage is 100%, so the baseline is 3, but the description adds substantial meaning beyond the schema. The 'TRADEABLE-EDGE KNOBS' section explains the purpose and interaction of each filter (e.g., min_partition_leg_kelly vs min_kelly, slippage context, spread/liquidity thresholds). It also clarifies defaults and edge cases, making the parameters much more actionable.

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, specific verb+resource+scope: "Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price." It also states the intended use case ("what should I bet on today") and distinguishes itself from sibling tools by focusing on Pipeworx disagreement and structured segments, rather than generic arbitrage or tracking.

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

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

The description clearly indicates when to use this tool: for discovering betting opportunities without paging through many markets. It also provides exclusions (e.g., Fed bets are surfaced but excluded from ranking with a caveat) and notes that certain segments are 'rare-by-design.' However, it does not explicitly name alternative sibling tools or say 'use X instead' for other use cases.

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

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

Even with readOnlyHint and idempotentHint annotations, the description adds substantial behavioral detail: the 60-day snapshot TTL, decay computed from daily closes net of slippage rather than intraday, snapshots only written on cache-miss, edge_pp_net being signed by trade direction, and the semantics of expired[] entries. This goes well 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 long but well-structured with labeled sections (Args, RESPONSE, LIMITS), and each sentence adds value. It is not lean, but the density is appropriate for a tool with such complex behavior and no output 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?

With no output schema, the description compensates thoroughly by enumerating response entries tracked[], expired[], snapshot_dates[] and explaining their fields and meanings. It also covers history depth and limitation context, making the tool's behavior predictable in context.

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

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

Schema coverage is 100%, so the baseline is 3. The description restates days/window defaults and qualifies window as a 'snapshot family,' but it does not materially expand on schema details like the 2-30 clamp or the exact enum values.

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 names a specific resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and poses a targeted question, 'how long has this edge existed and is it shrinking?' It distinguishes itself from siblings like polymarket_edges by focusing on time-series persistence rather than current edge values.

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 clearly conveys when to use the tool: to understand edge history across daily snapshots, noting that a fresh wide edge and a 3-week-old wide edge are different trades. It also provides context on snapshot gaps and TTL limits, though it does not explicitly name alternative tools or state 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds extensive behavioral detail: both single-market and basket modes, return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, capture_ratio, thin_legs[], etc.), and the warning that partial basket fills convert an arb into directional exposure. No contradiction with annotations.

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

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

The description is long and dense, but it is well-structured with clear sections for single-market and basket modes, and every sentence carries information. It is front-loaded with the main purpose. The use of all-caps for emphasis and the sheer length (though justified by complexity) keep it from a perfect score.

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

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

Despite lacking an output schema, the description fully enumerates return values for both modes, explains verdict values, list of thin legs, forced directional risk, and provides safety context. It is complete for a tool with 4 optional parameters and two distinct operational modes.

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

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

Schema covers all 4 parameters, but the description adds crucial cross-parameter meaning: mutual exclusivity of market vs event, mode-dependent interpretation of side (default auto in basket mode) and size_usd (spend/proceeds vs settlement notional), and the clamp range. It also notes that REQUIRES one of market/event, which is not in the schema's required list.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes from siblings by explicitly naming polymarket_arbitrage and polymarket_edges as tools whose signals this tool should precede.

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 when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround on thin books is not capturable, partial fills create unhedged directional risk). This is a clear directive with alternatives implied.

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

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

Far beyond the readOnly/openWorld/idempotent/destructive annotations, it discloses compatibility_warning and compatibility_codes, the standing fee limitation ('every spread_pp is gross, not a net tradeable edge'), skipped comparison counters, and the specific null semantics of temporal_alignment. It also clearly states that unknown-type legs are never paired and that pairing is not verified via a shared resolution source.

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?

It is a long description, but the CAPS-labeled sections like TWO MODES, RESPONSE, and SAFETY FIELDS keep the detail navigable and front-load the core purpose. Some enumerations, such as the compatibility codes and counters, are dense, though most sentences earn their place because there is no output schema to carry the return semantics.

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?

Because there is no output schema, the description fully specifies the return contract: leg-by-leg raw probabilities, top_spreads_pp with per-entry flags[], skipped_unclassified, low_confidence_pairs[], temporal_alignment semantics, fees_note, and skipped counters. It also covers optional parameter combinations and the meaning of null. Very little is left to inference.

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 coverage is 100%, so the schema already documents topic, kalshi_event_ticker, and polymarket_event_slug with examples and override semantics. The description adds the two-mode framing and the 'identical token-overlap matcher' caveat, but most parameter meaning is already present 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?

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which pinpoints the exact resource and purpose. It is clear about comparing the same question across two venues, but the phrasing is a noun phrase rather than an explicit verb and it does not name or contrast sibling tools like polymarket_arbitrage.

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

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

'TWO MODES' explicitly tells the agent when to use pre-mapped topic shortcuts versus custom ticker/slug pairings, and notes that both modes use the identical matcher. It also warns that most pre-mapped topics currently return compatibility_warning and that pre-mapped does not mean tradeable, though it never names alternative tools or explicit when-not-to-use conditions.

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 context beyond those: the scope ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the conditional listing behavior when the key is omitted. This is useful but not exhaustive (e.g., no return format details), a slight gap.

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

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

The description is three sentences, front-loaded with the core action, followed by usage context and scope. Every sentence contributes: no filler or repetition of schema/annotations. It is concise and well-structured.

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

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

For a single-parameter read tool with strong annotations and no output schema, the description covers all necessary aspects: what it does, when to use it, how it relates to siblings, and scope. The absence of return format details is acceptable because no output schema exists and the behavior is straightforward.

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 description for the 'key' parameter already covers it fully (100% coverage). The main description adds meaning by clarifying that omitting the key lists all keys and tying it to the 'remember' workflow. This exceeds the baseline, though it doesn't provide examples of key value formats or edge cases.

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 specific verbs and resources: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This clearly distinguishes from sibling tools like remember (save) and forget (delete), 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: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names alternatives/pairings: 'Pair with remember to save, forget to delete,' giving clear context on when to choose this 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 states that mark_read:true flags events read, mutating persisted state, while annotations declare readOnlyHint:true (no state changes). This is a direct contradiction. The description otherwise adds context, but the contradiction forces a minimum score.

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

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

The description is concise and front-loaded with the core purpose. Each sentence adds valuable information (return structure, filtering, mark_read semantics, polling, external endpoint) without unnecessary fluff.

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

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

With no output schema, the description adequately covers return shape (source, citation_uri, payload) and key behaviors (mark_read side effects, polling compatibility, external URL). It is complete for a 5-parameter tool with no output schema.

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

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

Schema descriptions cover 100% of parameters, so baseline is 3. The description adds extra meaning beyond the schema for type, since, and especially mark_read (explains the effect on subsequent calls), elevating it above baseline.

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

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

The description clearly states the tool pulls fired events from the user's subscription feed, distinguishing it from related tools like list_subscriptions and recent_changes. It specifies the resource and the action with sufficient detail.

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 ('Polls work fine') and offers an alternative for scripts/dashboards via a URL. It does not explicitly contrast with sibling tools, but the alternative guidance and filtering examples give adequate direction.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, so the bar is somewhat lower. The description adds valuable behavioral context: parallel fan-out to multiple sources, GDELT→GNews fallback on rate-limiting/5xx, and USPTO soft-fail due to PatentsView API sunset. It also states the return shape, making runtime behavior more predictable.

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 each sentence earns its place: query examples, source details with fallback logic, `since` format, return value summary, and sibling differentiation. It is front-loaded with the core purpose and follows a logical structure that an agent can parse efficiently.

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 (multi-source, fallback behavior, soft-fail, windowed queries) and the absence of an output schema, the description covers all essential aspects: input semantics, sourcing behavior, failure modes, and return structure (changes[], total_changes, citation URIs). It is sufficiently complete 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?

Schema coverage is 100%, so the baseline is 3. The description adds extra utility by expanding `since` with examples (ISO date or relative shorthand) and recommending '30d' or '1m' for typical monitoring. It also reinforces that only company type is supported, matching the schema enum, though it does not add much 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 clearly identifies the tool as a 'change feed for a company' over a time window, listing concrete sources (SEC EDGAR, GDELT/GNews, USPTO). It also distinguishes itself from the sibling tool entity_profile by explicitly stating when to use that instead.

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 opens with natural-language query examples that signal appropriate use cases, explains it fans out in ONE parallel call, and provides an explicit directional alternative: 'Use entity_profile instead when you want the static profile...' This gives an agent strong when-to-use vs. when-not-to-use guidance.

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

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

The description adds valuable behavioral context beyond the annotations: memory is scoped by the agent's identifier, authenticated users get persistent storage, and anonymous sessions retain memory for 24 hours. It doesn't explicitly mention overwrite behavior for existing keys, but the idempotentHint annotation partially covers this, and the described scoping and retention rules are significant additions.

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 compact sentences, front-loaded with the core action ('Save data...'), followed by usage context and storage details. There is zero redundancy—every sentence adds necessary information, and the structure is logical and easy to scan.

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

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

For a simple 2-parameter tool with a 100%-covered schema and informative annotations, the description fully covers the operation, when to use it, storage scope, and retention policy. Since no output schema exists or is needed, the description is sufficiently complete for an agent to 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 covers 100% of the parameters, including types and examples for key and value. The description reinforces the key-value nature ('Stored as a key-value pair') and gives examples of values ('findings, addresses, preferences, notes'), but it doesn't add substantive new syntax or format details beyond the schema. With full schema coverage, 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 saves data for later reuse, using the specific verb 'Save' and resource 'data' (memory). It also distinguishes itself from sibling tools by explicitly naming recall (retrieve) and forget (delete), giving concrete examples of what to store.

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 guidance on when to use: 'Use when you discover something worth carrying forward' and gives examples. It also names alternatives with clear pairings: 'Pair with recall to retrieve later, forget to delete,' effectively telling the agent when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context beyond those: graceful degradation if GLEIF/OpenFIGI fail, ambiguity handling via figi_candidates, explicit unresolved fields, source attribution for identifiers, and cascading internal lookups. 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 front-loaded with purpose and usage, and every section contributes unique information. It is long and dense with parentheticals, which hurts readability, but the complexity of the tool justifies the length. It is more exhaustive than concise, yet 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?

Given no output schema, the description carries the burden of explaining return behavior, and it does: identifiers labeled by source, unresolved fields, figi_candidates on ambiguity, and fallback behavior. It also covers supported inputs, entity types, and edge cases. An agent has enough context 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?

Schema description coverage is 100%, so the baseline credit is earned by the schema. The description goes further with concrete examples for both type and value, including the negative instruction to pass the issuer name only for bonds and not trailing security-class words. This materially helps an agent choose correct parameter values.

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 concrete natural-language triggers and a clear verb+resource: resolve a user-spoken name to canonical identifiers. It distinguishes itself from siblings like entity_profile and compare_entities by positioning itself as the name-to-ID lookup tool, and it enumerates supported types (company, drug) with specific identifier outputs.

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID,' which is a strong usage directive. It also gives conditional guidance by entity type and input format. However, it does not explicitly state when NOT to use this tool or name alternative tools, so it falls slightly short of full exclusion/alternative guidance.

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

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

The description goes beyond the annotations by disclosing the internal process: 'Probes each entity ... with ai_visibility_check' and the return format: 'Returns ranked list with score, confidence, signal density per entity.' The annotations already declare read-only and non-destructive behavior, and the description adds useful context without contradicting them.

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

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

The description is three focused sentences: first states the purpose, second details the mechanism and output, third supplies a use case. Every sentence adds value and there is no repetition or fluff.

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

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

Given the tool's moderate complexity and the presence of annotations, the description is complete. It explains what the tool does, how it works (probes via ai_visibility_check), what it returns (ranked list with score, confidence, signal density), and when to use it. No output schema exists, so the description properly covers the return value.

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

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

Schema description coverage is 100%, so the input schema already fully explains each parameter. The description does not add new parameter-level meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes from sibling tools by mentioning the method (probing with ai_visibility_check) and the comparison aspect, which differentiates from ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description provides a concrete use case: 'Useful for competitive AI-marketing audits: "does Claude know about us as well as our competitors?"' This clearly conveys when to use the tool. However, it does not explicitly mention alternatives or when not to use it, so it stops short of full 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?

The annotations already declare readOnly/idempotent, but the description adds valuable behavior beyond that: it discloses composite fan-out, partial failure degradation ('sources_failed will list it'), and a critical timing caveat ('bundlephobia's first measurement can take 5-30s'). This is far beyond what annotations provide.

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

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

The description is long but every sentence earns its place: purpose, use cases, output format, ecosystem limitation, and failure behavior. It's front-loaded with the core purpose and structured with dashes and clauses. No fluff.

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

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

Given no output schema, the description fully explains the return value: summary block fields, per-advisory detail, links, alternative versions, and the sources_failed field. It also covers latency and ecosystem scope, making it complete for a complex composite 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 both parameters well documented. The description does not add new parameter-level semantics beyond what the schema already states (e.g., scoped packages and default version are already in the schema). It adds context around the composite behavior but not parameter syntax, so baseline 3 is appropriate.

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

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

The description opens with a specific, vivid purpose: 'Composite "should I add this npm package to my project" check in ONE call'. It clearly names the resources (deps.dev, bundlephobia) and the scope (npm v1). This distinguishes it from sibling tools like validate_claim or deep_research.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion and alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This is model behavior for usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds value by disclosing the output format and that it returns names only, not SVG data, which is beyond annotation information.

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 concise sentences, front-loaded with the purpose and then providing the output format and pointer to get_icons. No unnecessary words or repetition.

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

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

Given the tool's simplicity, full schema, output schema, and strong annotations, the description is complete. It covers purpose, output format, and the next step (get_icons), so no critical gaps remain.

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

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

The input schema has 100% coverage with descriptions and examples for both query and limit. The description itself does not add parameter-specific details, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool searches for icons by keyword across all collections, which is specific and distinguishing. It also mentions the output format (prefix:name), further clarifying its purpose relative to get_icons.

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 directs users to use get_icons to fetch SVG data, indicating when to use this tool as a search step. It provides clear context for when this tool is appropriate, though it lacks an explicit when-not-to-use statement for other 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 mark this as readOnly/idempotent, but the description adds significant behavior: returns character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char overlapping windows, enforces a 200K char cap with truncation flag. This goes well beyond the annotations and provides concrete operational details.

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

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

Three sentences, each earning its place: core function, use case, and technical detail. It is front-loaded and well-structured with no redundancy or filler. The description is appropriately sized for the information it conveys.

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

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

Despite no output schema, the description fully explains return format (passages with offsets and similarity scores), input size cap, truncation behavior, and pairing with a sibling tool. It covers both the 'what' and the 'how' faithfully, making the tool self-contained for an agent.

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

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

Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description reinforces the text param by saying 'pass the text you already pulled' and implies limit via 'top-N,' but it doesn't add meaning beyond what the schema already provides. This is consistent with the high-coverage baseline.

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

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

The description opens with 'Semantic search INSIDE a fetched record' — a specific verb+resource that clearly distinguishes it from sibling tools. It further specifies inputs (text + query) and outputs (top-N passages with offsets/scores), leaving no ambiguity about 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?

Explicitly states the trigger: 'Use when the record is too big to cram into the prompt.' It also names a sibling pairing: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages.' This gives clear when-to-use and an alternative workflow, making it easy for an agent to select this tool appropriately.

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 richly augments the annotations. It discloses the account requirement, email/SMS delivery constraints (phone verification, 10/day cap), webhook behavior (signing secret, auto-disable after 10 failures), and the fact that the feed is always on. These details go well beyond the annotations' readOnlyHint/idempotentHint flags, providing deep behavioral 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 structured with clear sections for type and delivery channels, and it front-loads the core action. It is lengthy due to the tool's complexity but remains well-organized. However, it repeats some schema details and lists only three of five supported types, making it slightly more verbose than necessary.

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 many aspects (OAuth requirement, feed delivery, email/SMS) but has notable gaps: it omits two supported types (patent_grant, clinical_trial) and the webhook delivery channel entirely. These are present in the schema, so an agent relying solely on the description might underestimate the tool's capabilities, creating a completeness shortfall.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The tool description adds extra meaning by providing concrete examples for types (e.g., sec_8k items ['5.02'] for officer change) and delivery-specific constraints (e.g., sms phone verification, webhook signing secret, 10/day cap). This enhances the schema's baseline 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 primary function: 'Create a proactive monitoring subscription to a live-data event stream.' It also specifies the return value ('Returns the new subscription id'). This is specific and distinct from sibling tools like list_subscriptions and unsubscribe, which manage existing subscriptions.

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

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

The description provides clear context on when to use the tool: to create a monitoring subscription. It also includes a key exclusion: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions),' which tells users when not to use it. However, it does not explicitly mention alternatives like list_subscriptions for viewing existing subscriptions, so it falls short of full when-to-use vs alternative guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so safety is covered. The description adds valuable behavioral context: it details return contents (category-bucketed examples with tool + argument shapes) and the live-catalog sourcing, going beyond the annotation baseline.

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 average but well-structured: trigger phrases, purpose, return details, then usage. Each section earns its place, though the list of trigger phrases could be trimmed without losing core 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?

With no output schema, the description fully explains what the tool returns, the optional topic parameter effect, and when to use it. It covers all necessary context for an agent to invoke the tool correctly and interpret results.

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

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

The schema already documents the 'topic' parameter thoroughly, including the exact list of focus areas and the 'Omit for a cross-category spread' instruction. The description adds only examples like 'finance', 'pharma', 'betting' but no new semantic meaning, so baseline 3 is appropriate.

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

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

The description explicitly states the tool returns category-bucketed example questions with the exact tool and argument shape, and frames itself as the onboarding entry point. It clearly distinguishes from siblings by naming its role as 'Use this FIRST' when unsure what Pipeworx can do.

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

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

Provides explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and how to learn to call meta-tools. Also explains when to omit or pass 'topic', giving clear conditions for different invocation modes.

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=false and idempotentHint=true, but the description adds critical context: the row is deactivated (not deleted), ensuring historical events remain available via recent_alerts. Also clarifies ownership enforcement, going beyond the annotations.

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

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

Two sentences with zero waste. Front-loaded with the action, followed by two important behavioral notes (ownership and deactivation). No extraneous content.

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

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

For a one-parameter tool with no output schema, the description covers the main action, a key constraint, and the post-effect (deactivation preserving history). It doesn't describe the return value, but given the simplicity, the description is largely complete.

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

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

Schema coverage is 100% with 'id' described as 'Subscription id (uuid) returned by subscribe.' The description restates 'by id' but does not add additional parameter details beyond what the schema already provides. 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 starts with 'Cancel a subscription by id', a specific verb+resource combination that clearly distinguishes the tool from siblings like 'subscribe' and 'list_subscriptions'. It also mentions ownership enforcement, adding scope.

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

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

The description mentions ownership enforcement ('you can only cancel your own subscriptions') as a constraint, and the deactivation note implies a safe way to cancel while preserving history. However, it does not explicitly state when to use this tool over alternatives or provide 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses important behaviors: the two routing paths, the exact verdict values returned, the critical distinction between could_not_verify (with verification_error) and unsupported, and the mention of verbatim evidence with pipeworx:// citations. This is rich behavioral context that helps an agent interpret results and avoid misusing error states.

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 yet efficient. It front-loads example utterances to signal intent, then methodically covers usage, routing, return values, and error semantics. Every sentence contributes substantive information; there is no fluff or repetition.

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

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

Despite the lack of an output schema, the description fully explains what the tool returns: verdicts, actual values with citations, and reasoning. It also clarifies the semantics of could_not_verify and unsupported, which are crucial for correct downstream handling. Given the tool's moderate complexity, the description is complete.

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

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

The schema already covers both parameters 100%, but the description adds significant value: for tolerance_pct it explains how to override the implied tolerance, gives the range and a specific use case (hallucination detection), and states the default behavior. For claim it provides clear examples. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with specific example phrases ('fact check', 'verify the claim that…'). It distinguishes itself from generic Q&A tools by describing the structured SEC EDGAR fast path for company-financial claims versus a grounded pipeline for all other claims, and notes 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?

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear when-to-use guidance. It also details routing logic for company-financial vs. other claims. However, it does not explicitly mention alternative tools to use instead (e.g., ask_pipeworx for general queries), so it lacks the 'when-not' or alternative comparisons needed for a 5.

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