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, so the description's main job is to add context. It adds useful behavioral details: routing across 5,407 tools, filling arguments, returning citations, and being fast on every tier. No contradiction with annotations, and it supplements them well, though it doesn't discuss failure modes or limits.

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 most important guidance ('PREFER OVER WEB SEARCH', 'START HERE'). Each section earns its place with concrete examples and sibling distinctions. Some redundancy exists between the domain list and the trigger-phrase list, but overall the density is high and structure is purposeful.

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 explains the return format ('structured answer with stable pipeworx:// citation URIs'), lists many covered domains, gives concrete examples, and clarifies positioning relative to siblings. Given the tool's broad scope, this description provides enough context for an agent to select and invoke it appropriately.

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

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

The schema already provides 100% coverage for all parameters, including explicit alias descriptions. The description adds examples and routing context but does not deepen parameter semantics beyond what the schema states (natural language question, accepts aliases). This is baseline for 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 opens with a clear directive to prefer this tool over web search, then names the exact resource ('5,407 tools across 1403 verified sources') and the action ('routes the question... returns the structured answer with stable pipeworx:// citation URIs'). It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point.

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

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

Explicitly says 'START HERE for most questions', provides a list of trigger phrases ('what is', 'look up', 'find'), and names alternatives with specific when-to-use conditions: ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions. This is exemplary 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, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable context: it is a beta with candidate routing improvements, currently none active, so behavior matches stable exactly. It also clarifies it is a full working router with no fallback, 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?

The description is slightly long but every sentence contributes meaning: beta identity, identical core, current state, usage guidance, and fallback explanation. It is well-structured and front-loaded with the key differentiator, though the parenthetical could be slightly 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?

Given the simple schema (one meaningful parameter) and rich annotations, the description sufficiently covers the beta nature, current equivalence to stable, and comparison purpose. It lacks a detailed explanation of the universal router's internal behavior, but that is not necessary for usage. No output schema exists, but the description notes the same response shape.

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 (aliases for 'question') fully described. The description only says 'same arguments' without adding detail, so it relies on the schema. Baseline of 3 is appropriate since the schema carries the full 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 identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,407 tools, arguments, and response shape. It distinguishes from the stable sibling by explaining the experimental routing improvements and provides a concrete use case (newest routing).

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

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

The description explicitly instructs to use it exactly like ask_pipeworx when wanting the newest routing, and notes that results are compared against the stable router. It implicitly steers users to the stable ask_pipeworx for non-experimental use, but does not explicitly name alternative tools or state when not to use, so it falls just 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?

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals refusal behavior, return structure (answer, evidence, confidence, source, fetched_at, refusal_reason), specific refusal reasons, and the fact that it uses only tool results. This adds significant behavioral context not inferable from annotations alone.

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

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

The description is dense but well-structured. Each of the 4 sentences serves a distinct purpose (behavior, return format, usage, cost tradeoff), though the first sentence is long and packs multiple clauses. Slightly more verbose than necessary but every piece earns its place.

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

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

Given the tool's complexity, lack of output schema, and high-stakes use case, the description is remarkably complete: it covers return value shape, refusal reasons, routing behavior, source count, cost, and alternatives. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100% for all 6 parameters (all aliases for 'question'), and each parameter already has a clear description in the schema. The tool description does not add parameter-level details beyond what the schema provides, so 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 states the tool's purpose: a hallucination-resistant answer mode for high-stakes reads. It specifies the verb ('answer'), resource ('Pipeworx'), and key behavior (grounded extraction), and distinguishes itself from sibling 'ask_pipeworx' by highlighting its refusal mechanism and evidence-based answers.

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

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

Explicit guidance is provided: use when answers will be quoted, cited, or acted on and must not invent facts, with concrete examples (financial, legal, medical). It also names the alternative ('prefer ask_pipeworx for casual lookups') and notes the cost tradeoff of an 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?

Beyond the annotations (read-only, open-world, idempotent, non-destructive), the description discloses critical behavioral traits: requires sign-in, paid tier for 'thorough', latency expectations (15-90s), gap[] behavior (never invents data), contradictions[] for standard/thorough, semantic excerpting of large records, and the presence of hop/citation fields. This is rich, valuable context that annotations alone do not provide, and 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 lengthy but every sentence carries unique information: account requirements, core capability, alternative tools, depth behaviors, output structure, latency, and caveats. It is well-organized and front-loaded with critical account info, though it could be slightly more scannable with section breaks. The density justifies the length for such a complex tool.

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

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

Given the tool's complexity, the description is remarkably complete. It explains what the return packet contains, gap[] and contradictions[] handling, citation URIs, latency, and the difference between depth levels. With no output schema, the description fully covers return-value expectations and caveats, leaving little ambiguity for the 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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema. It interprets the 'depth' parameter in behavioral terms (quick=3 facets, standard=5 with gap recovery + contradictions, thorough=8 with iterative hop) and clarifies that 'question' should be broad/multi-part since decomposition is the point. This enriches the parameter understanding beyond the enum 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 with a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1403 STRUCTURED data sources' in ONE call. It explicitly distinguishes itself from open-web search and from sibling tools like ask_pipeworx, making its unique role immediately obvious.

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: 'Best for broad/multi-part questions over structured data,' and also specifies when NOT to use it: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also covers account prerequisites and fallback behavior if not signed in, giving a complete usage decision framework.

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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds practical behavioral context beyond annotations: it fans out across multiple sources, calls them 'in ONE parallel call', mentions the USPTO PatentsView API sunset with 'soft-fails until reactivated', and describes a GDELT→GNews fallback. This gives a clear picture of internal behavior and dependencies.

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 each sentence carries substantive information: query examples, preferred usage, fan-out sources, return fields, and input constraints. It is front-loaded with the core purpose and then details the scope. No filler or redundancy; 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?

There is no output schema, so the description must explain return values. It lists the main output components: cik, company_name, recent_filings with URIs, fundamentals (from latest 10-K), patents, news mentions, and LEI. It also covers input edge cases (ticker/CIK only) and source reliability (patent API sunset). While it doesn't provide exact JSON structure or types, the field list and caveats make it sufficiently complete for an agent to use.

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

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

Schema coverage is 100%: both 'type' and 'value' are fully described. The description adds value by providing concrete examples (ticker 'AAPL', zero-padded CIK '0000320193'), explicitly stating names are not supported and recommending resolve_entity as a prerequisite. This goes beyond the schema by clarifying the exact format and usage patterns.

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: 'full cross-source profile of a US public company in ONE parallel call.' It uses specific verbs like 'profile' and 'research' and explicitly distinguishes itself from sibling tools by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' This differentiates it well from related tools like deep_research and compare_entities.

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

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

The description provides explicit guidance on when to use this tool: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives a clear exclusion: 'names not supported (use resolve_entity first if you only have a name),' pointing to the alternative for name-only queries. This is strong when/when-not guidance.

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

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

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

Annotations are all false, providing no side-effect info, so the description carries the burden. It adds valuable behavior traits: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, and that the team reads digests daily and signal affects roadmap. It doesn't mention what happens after submission (e.g., whether a confirmation is returned), but overall it's transparent for a feedback channel.

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 compact and front-loaded, with the core purpose in the first sentence. Every subsequent sentence earns its place: usage triggers, content guidance, and operational constraints (rate limit, quota, digest). No fluff or repetition of schema details. It's about 6 short sentences, appropriate 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?

For a feedback tool with 3 parameters (one nested), a detailed schema, and no output schema, the description covers all essential context: when to use, what to include, what not to include, and operational constraints. It doesn't need to describe return values since there is no output schema. The guidance on describing issues in terms of tools/packs is valuable and complete for an agent to invoke this 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% with thorough descriptions for all parameters, which sets a baseline of 3. The description adds extra semantic guidance beyond the schema: 'Describe the issue in terms of Pipeworx tools/packs' and 'don't paste the end-user's prompt,' which directly informs the 'message' parameter. It also explains the meaning of feedback types in the usage line, reinforcing the enum 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 purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific feedback types (bug, feature, data_gap, praise) and distinguishes itself from sibling tools, which are largely research/analysis tools. The verb 'Tell' plus the resource 'Pipeworx team' makes the action explicit.

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

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

Provides explicit when-to-use conditions for each feedback category: '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 gives a clear exclusion/don't instruction: 'don't paste the end-user's prompt.' This leaves no ambiguity about appropriate use.

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

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

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

Despite annotations already declaring readOnly, openWorld, and idempotent, the description adds substantial behavioral detail: safety fields (compatibility_warning with two distinct cases), temporal_alignment semantics, and skipped_cross_type/subtype counters. It also transparently notes that pre-mapped ≠ tradeable. This goes far beyond the annotations.

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

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

The description is dense and long, but every sentence carries operational information (modes, safety flags, temporal alignment, counter semantics). It is front-loaded with the core purpose. While somewhat verbose, it earns its length given the tool's complexity.

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

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

With no output schema, the description explains return values in detail: leg-by-leg prices, matched spread[].top_spreads_pp, compatibility_warning triggers, temporal_alignment, and skipped counters. It covers edge cases and failure modes, 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 each parameter described, but the description adds critical interaction semantics: how topic auto-fetches, how explicit tickers override the topic-mapped side, and the exact list of valid topic strings. This enhances the schema rather than merely repeating it.

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 precise definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly states the tool's function and differentiates it from siblings like polymarket_arbitrage and polymarket_edges. The two modes (topic shortcuts vs. explicit tickers) further clarify 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 explains when to use each mode (topic shortcuts vs. explicit tickers), and explicitly warns that most pre-mapped topics return compatibility_warning today, setting expectations. However, it does not explicitly name sibling tools as alternatives (e.g., 'use polymarket_arbitrage for intra-venue opportunities'), so guidance could be more direct.

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, but the description adds rich behavioral context: it mentions internal cascading through multiple endpoints, auto-disambiguation, specific return fields (ticker, CIK, company_name, RxCUI, ingredient, brand), and citation URIs. This goes well beyond the structured annotations.

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

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

The description is somewhat long but well-structured: it starts with concrete query examples, then a clear purpose statement, then a directive, then a detailed breakdown of supported types. Every sentence contributes useful information, though it could be tightened slightly without losing value.

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

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

Despite having no output schema, the description fully explains what each entity type returns, including specific fields and citation URIs. It also covers usage context, internal behavior, and parameter semantics, making it entirely sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% and each parameter already has descriptive text. The description adds meaning by explaining the return values associated with each type and noting auto-disambiguation, which helps the agent understand the consequences of choosing 'company' vs 'drug'. It enhances but does not drastically expand on 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 ('resolve') and resource ('user-spoken NAME to the canonical/official identifier'), with concrete examples like ticker, CIK, and RxCUI. It clearly distinguishes from siblings by stating it produces identifiers other tools require as input, and it explicitly lists supported types with expected 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 gives a clear directive: 'Use FIRST whenever you have a name but need an ID' and explains the internal cascade replacing 2-3 manual lookups. However, it does not name specific alternative tools or explicitly state when not to use it, so it lacks full exclusionary 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds useful context: the routing logic to SEC EDGAR vs. grounded pipeline, the use of 'exact percent-delta math', and that it returns verdicts with citations. This enriches beyond the annotations without contradicting them.

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

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

The description is lengthy but well-structured: it starts with trigger phrases, then states the primary use, details the two verification paths, lists the return values, and concludes with the efficiency benefit. Each sentence contributes unique information, making it appropriately sized for the tool's complexity.

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

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

With no output schema, the description adequately explains return values (verdict types, citation, reasoning). It covers both claim categories and provides examples, making it complete for an agent to select and invoke correctly. The complexity is fully addressed without leaving critical gaps.

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

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

The schema already covers both parameters 100% with descriptions. The description adds practical guidance for `tolerance_pct`, such as setting 1–2 for hallucination detection and explaining the default is implied by wording and capped at 5, which goes beyond the schema's static description.

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

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

The description clearly states the tool's purpose: 'natural-language claim verification against authoritative sources' with specific trigger phrases like 'fact check' and 'verify the claim that…'. It distinguishes itself from generic Q&A tools by focusing on returning verdicts (confirmed/refuted/etc.), making its role unambiguous.

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

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

It 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 differentiates between company-financial claims (SEC EDGAR path) and other claims (grounded pipeline), but does not name alternative tools or exclusions, so it misses the top score.

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