Imf

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context beyond these: the default model choice (Workers AI Llama-3.3-70b, free), the BYO-key requirement with direct cost to the user for Anthropic calls, and the return payload shape. This meaningfully extends 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 three sentences, front-loaded with purpose, and every sentence contributes: what it does, usage and cost details, output format, and use cases. No filler or redundancy.

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

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

For a read-only probe tool without an output schema, the description covers inputs (entity, models, key, context), default behavior, output structure (per-model + combined view), and use cases. It also mentions cost and authorization, making it complete for the tool's complexity.

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

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

Schema covers all 4 parameters at 100%, so baseline is 3. The description adds a small amount of extra semantics: names the default model and clarifies cost implications for _apiKey, which goes beyond the schema. However, most parameter behavior is already in the schema, so not a 5.

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

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

The description uses a specific verb ('Probe') with a clear resource ('one or more LLMs') and outcome ('score visibility (0-100) per model'). It distinguishes itself from siblings like scan_competitor_ai_presence by emphasizing LLM knowledge scoring rather than competitor website scanning.

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

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

The description explicitly lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), giving clear context for when to use. However, it does not mention alternatives or when-not-to-use cases, so it stops short of a 5.

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

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

Annotations already cover read-only and idempotency. The description adds valuable behavioral context: it routes to 5,635 tools, returns pipeworx:// citation URIs, is fast, and works on every tier. This goes beyond the annotations by explaining the routing and output characteristics. However, it doesn't mention rate limits or auth requirements, so it stops short of a 5.

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

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

The description is quite lengthy, listing multiple data domains, example questions, and alternative tools. While it is well-structured and front-loaded with the key 'PREFER OVER WEB SEARCH' directive, several sentences are redundant (e.g., the source list and the example list overlap). It would benefit from trimming to be more concise.

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

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

For a complex, entry-point tool with a simple schema and no output schema, the description is remarkably complete. It covers when to use it, when not to use it (via alternatives), what it returns (citations, structured answers), and even gives example queries. An agent has everything needed to invoke it correctly.

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

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

The schema has full coverage (100%) of the sole required parameter 'question', including aliases and examples. The description reinforces that the input is a natural language question and provides example phrasings, but these are already present in the schema. No additional parameter-specific meaning is introduced, so it falls at the baseline of 3.

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's purpose: it answers factual questions by routing to a large set of verified sources and returns structured answers with citations. It explicitly contrasts itself with web search and sibling tools (ask_pipeworx_grounded, deep_research), making its unique role unmistakable.

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

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

The description provides explicit when-to-use guidance (any factual question, with example phrasings like 'what is', 'look up') and when-to-step-up alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad multi-part questions). It also positions itself as the default entry point, leaving no ambiguity about selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it is a full working router (not a fallback), currently matches ask_pipeworx exactly, and may have routing improvements enabled during tests. 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 slightly long but well-structured, with the key point (beta version) front-loaded and subsequent sentences explaining status, usage, and nature. Each sentence earns its place, though it could be trimmed slightly without losing meaning.

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

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

For a complex router tool, the description covers its identity, relationship to ask_pipeworx, current state, and usage. It references the same response shape as ask_pipeworx, which is sufficient given no output schema is provided. It does not over-explain, but the missing explicit response format is acceptable due to the reference to ask_pipeworx.

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

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

Schema description coverage is 100%, with all parameters (question and aliases) already documented in the schema. The description only references 'same arguments' without adding further semantic detail, so it does not add value beyond the schema.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, an identical universal router with the same 5,635 tools, arguments, and response shape. It explicitly differentiates it from the stable ask_pipeworx by highlighting the experimental routing improvements and its current state. This distinguishes it from siblings like ask_pipeworx and ask_pipeworx_grounded.

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

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

It provides clear usage context: use it exactly like ask_pipeworx when you want the newest routing, and notes that results are compared against the stable router. However, it does not explicitly state when NOT to use it or contrast it with ask_pipeworx_grounded, but the guidance is sufficient for an agent to decide when to invoke it.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description reveals behavior: it never invents facts, uses only tool-result content, returns a structured refusal with five specific reasons, and adds a cost note. This is rich, non-obvious behavioral disclosure not present in 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 detailed but every sentence carries unique information: process, output structure, usage guidance, cost, and alternatives. It is front-loaded with the key benefit. Slightly dense but not verbose; earns a high 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?

Covers purpose, internal routing, output schema (including refusal reasons), usage context, cost, and relation to sibling tools. For a tool with no output schema, the description fully compensates by specifying return structure and error/refusal semantics.

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 descriptions, including alias handling, so the description adds little beyond what the schema already states. The baseline of 3 applies; no additional guidance on phrasing is provided, which is acceptable.

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

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

The description states a specific purpose: a hallucination-resistant answer mode that extracts answers strictly from tool results, with explicit contrast to the sibling ask_pipeworx. It clearly identifies verb (extract, return, refuse), resource (grounded answers), and distinguishes itself from casual lookups.

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

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

Explicitly says when to use (high-stakes reads, quoted/cited/acted-on answers) and when not (casual lookups) and names the alternative (ask_pipeworx) plus cost implication. This is textbook 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?

Even with annotations marking the tool as read-only and non-destructive, the description goes far beyond them. It discloses the resolver's matching confidence and alternatives, the short-circuit safety for low-confidence matches, the blocking behavior for closed/dead markets, wide-spread illiquidity flags, news fallback mechanisms with retry_after_sec, and detailed cancellation-rule parsing (refund_50_50, resolves_no_on_cancel, etc.). No annotation contradiction; this is exemplary 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 long but every sentence earns its place. It is structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, RESOLUTION-RULE RISK) and front-loads the core action in the first sentence. No fluff or repetition; the length is justified by the tool's complexity.

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

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

The tool has no output schema, so the description must explain the return values and edge cases—and it does thoroughly. It covers response shapes (result.market, result.analysis, result.evidence), resolver contract fields, parent-event extraction, news fallback states, safety statuses (low_confidence_match, market_closed_or_inactive, illiquid_wide_spread), and cancellation-rule risks. This is complete enough for an agent to invoke the tool correctly and interpret results across scenarios.

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 three parameters with descriptions (slug/URL/question text for market, quick vs thorough for depth, raw payload toggle for include_raw). The description adds extra value by giving concrete examples of accepted formats for market and illustrating thorough/depth behavior through fan-out examples. It also hints at include_raw implications via the response-shape and news-fields sections. This is above the baseline of 3 but not a 5 because the schema already does significant lifting.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states the tool's function, scope (Polymarket bets), and output (evidence packet + market-vs-model comparison). It also differentiates from siblings by focusing on specific bet research with classifier-driven data fan-out, rather than general Q&A or raw data access.

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 usage context: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' and includes examples (BTC, Fed, Hormuz, Yankees, hottest year, NVDA-vs-AAPL). It also gives advisory guidance like 'ALWAYS inspect these before trusting the analysis block' and 'Check this before sizing sports/esports/event-occurrence bets.' However, it does not explicitly name alternative tools or provide when-not-to-use conditions, so it falls just 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?

Beyond the readOnly/idempotent annotations, the description discloses key behaviors: pulls latest 10-K data for companies, handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. This adds substantial context about the tool's operation.

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 front-loaded with trigger phrases and the 'ALWAYS PREFER' guidance. While longer than the two-sentence ideal, every sentence provides operational detail (data sources, sorting, return format) with minimal 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?

With no output schema, the description fully explains the return value (paired data + citation URIs). It covers input constraints, per-type behavior, data handling nuances, and sorting, making it self-sufficient for agent 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 already covers both parameters (type enum and values array with descriptions), but the description adds richer semantics: what data each type pulls and the expected input formats (tickers/CIKs for company, names for drug). This enhances the agent's understanding beyond the schema alone.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single parallel call, with specific trigger phrases. It distinguishes itself from sequential lookups and sibling tools by emphasizing parallel comparison and listing data sources.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It also gives example user intents and explains what each type retrieves, making it easy for an agent to decide when to invoke 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 declare readOnlyHint/idempotentHint=true and destructiveHint=false; the description adds substantial behavior beyond that: 'never invented' gaps[], latency ('Expect 15-60s, thorough up to ~90s'), account/payment requirements, resolvable citation_uri semantics, contradictions[] for standard/thorough, and semantic excerpting of large records. All disclosed behaviors are consistent with read-only, idempotent, non-destructive annotations — no contradiction.

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

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

Well front-loaded with the most critical callability facts (account required, use alternative if not signed in) before the mechanism description. However, at roughly 700 words it is over-long: the second-hop iteration and contradictions[] details duplicate the schema's depth description, and color details like '5,635 tools' and '1,477 sources' don't earn their place for correct invocation. Dense and useful, but verbose.

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

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

With no output schema, the description must explain the return contract, and it does thoroughly: findings packet fields (verbatim evidence, confidence, source, fetched_at), gaps[], contradictions[], hop, and citation_uri semantics. Combined with the fully-covered 2-param schema, everything an agent needs to call and interpret this complex research tool is present — including latency and failure 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 coverage is 100% and the schema's depth description is already detailed (quick/standard/thorough facet counts and hop behavior), so the baseline of 3 applies. The description adds minor value beyond the schema — 'thorough needs a paid plan' and the operational meaning of decomposition — but doesn't significantly extend the parameter semantics already documented.

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

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

States a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1477 STRUCTURED data sources' that 'Decomposes your question into focused facets, routes each to the right one of 5,635 tools IN PARALLEL, and returns a findings packet'. Explicitly distinguishes from the sibling family it could be confused with: 'this is NOT open-web search', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. An agent cannot mistake this for its closest siblings.

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

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

Provides explicit when-to-use ('Best for broad/multi-part questions over structured data'), when-not-to-use ('For a single lookup use ask_pipeworx'; 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx' because deep_research 'returns mostly empty gaps[]'), and names the alternative tool directly. Even covers the access prerequisite: if not signed in, 'use ask_pipeworx instead — it works on every tier'. Routing guidance is unambiguous and actionable.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful behavioral context: returns top-N tools with full schemas and curated examples, ready to call directly with no second lookup. This goes beyond annotations, though it doesn't discuss limits or edge cases.

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 job: first states purpose, second gives usage context and domain list, third explains return value and the 'call first' guidance. No wasted words; information is front-loaded.

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

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

Despite lacking an output schema, the description fully explains what the tool returns (top-N tools with names, descriptions, and full input schemas with examples) and when to use it. This is complete for a meta-tool of this complexity.

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

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

Schema description coverage is 100%, so all parameters are already documented with descriptions and aliases. The description does not add parameter-specific semantics beyond what the schema provides, 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?

Clearly states 'Find tools by describing the data or task' with a specific verb and resource, and lists concrete domains (SEC filings, financials, FDA drugs, etc.). Distinguishes itself from siblings by being the discovery/meta tool, not a data-retrieval tool.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and advises 'Call this FIRST when you have many tools available and want to see the option set.' This gives clear when-to-use guidance even without naming 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 provide readOnlyHint, idempotentHint, and destructiveHint, but description adds rich behavioral details: it 'fans out across' multiple sources, returns specific fields with URIs, notes patents API sunset and soft-fail, and GDELT→GNews fallback. These behaviors are 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 a single dense paragraph, but it is front-loaded with user examples and the core promise. Each clause provides essential information (data sources, return fields, fallbacks, limitations). It is longer than ideal but every sentence earns its place; slight run-on structure prevents a 5.

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

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

With no output schema, the description must convey return structure, and it does thoroughly: enumerates return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and notable details (limit of 5 filings, LATEST 10-K, API sunset). Also covers input constraints and fallbacks, making it complete for a complex 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% and the schema descriptions already explain ticker/CIK and name-not-supported. The description repeats these semantics, adding no new meaning. Baseline 3 is appropriate; there is no gap to compensate.

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

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

Description clearly states it produces 'full cross-source profile of a US public company in ONE parallel call' and enumerates the specific data sources and returned fields. It distinguishes itself from siblings by explicitly preferring it over chaining single-pack lookups and referencing resolve_entity for names.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also gives alternatives: 'names not supported (use resolve_entity first if you only have a name).' This clearly tells when to use and when to use another 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 destructiveHint=true and idempotentHint=true. The description adds useful context about what gets destroyed (a previously stored memory by key) and specific scenarios (clearing sensitive data), aligning with annotations without contradiction.

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

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

The description is two sentences, front-loaded with the primary purpose, and contains no extraneous information. Every phrase earns its place, making it highly efficient.

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

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

For a simple one-parameter destructive tool with annotations covering safety, the description provides complete context: what it does, when to use it, and its relation to siblings. No output schema is needed for this operation, and the annotation profile ensures the agent understands the destructive nature.

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

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

The input schema fully documents the required 'key' parameter with a clear description ('Memory key to delete'). The tool description also mentions 'by key,' but adds no additional format, syntax, or edge-case details beyond the schema, so the schema carries the semantic load.

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: 'Delete a previously stored memory by key.' It uses a specific verb (delete) and resource (memory), and distinguishes itself from sibling tools like remember and recall by describing the deletion operation.

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 when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also suggests pairing with remember and recall, giving clear context and complementary tool relationships.

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=true, idempotentHint=true, etc. The description adds valuable process detail ('Fetches the page, extracts title/description/key links') and output format ('single text blob'), going beyond what the annotations declare. No contradictions; behavior is consistent with a read-only, idempotent operation.

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 with a clear front-loaded purpose, a process summary, and a bulleted 'Useful for' list. Every sentence earns its place; no filler 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?

For a simple two-parameter tool with rich annotations and schema coverage, the description fully covers the return value ('single text blob ready to drop at site-root/llms.txt'), use cases, and behavioral guarantees. No output schema exists, so the explicit output mention is sufficient.

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

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

Input schema describes both parameters fully with examples and defaults ('Full URL of the site to summarize', 'Maximum number of link entries to include (default 25, max 50)'). The description adds no extra parameter-specific meaning, so baseline 3 is appropriate for 100% 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 a specific action ('Generate a production-ready llms.txt file') against a resource ('for any URL'), and even specifies the output format ('emits the standard llms.txt markdown format'). This is distinct from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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 explicitly lists three concrete scenarios: getting a client's site indexed, drafting your own llms.txt, or auditing a competitor. This gives clear context for when to use, though it stops short of explicitly naming alternatives or when-not-to-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?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses that omitted dimensions are left open and return every code, that dimension schemas vary by dataset, and that the return includes {period, value} plus dimension values. These are useful behavioral details not fully captured 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?

Five sentences, front-loaded with the core purpose, then a concrete example, a caveat, a behavioral rule, and the return format. Every sentence earns its place and there is no fluff or redundancy.

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

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

Given the rich annotations, a fully described input schema, and an output schema, the description fills remaining gaps: open dimension behavior, dataset-specific schemas, and the return shape. It is complete enough for an agent to invoke correctly, especially with the pointer to search_indicators.

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

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

The input schema already provides full descriptions for all 5 parameters (100% coverage), so the baseline is 3. The description adds a concrete example call and a caveat about dataset-specific dimensions, but similar guidance already appears in the schema's dimensions description ('Use search_indicators to discover valid names and codes').

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 'Fetch an IMF time series', a specific verb and resource, and explains identification via dataset plus a dimensions map. This clearly differentiates it from siblings like get_datasets (list datasets) and search_indicators (discover dimensions).

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 'Dimension names and order differ per dataset — use search_indicators to see what a dataset accepts', naming the correct alternative tool for discovery. This gives clear context on when to use get_data versus search_indicators and implies prerequisites.

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, so safety is covered. The description adds value beyond annotations by explaining that the tool returns a dataset id, name, and description, and that this id is meant to be passed to get_data and search_indicators. This downstream usage context is useful behavioral information not present in the schema.

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-organized, starting with the core action ('List or search'), followed by concrete examples of datasets, return semantics, and query usage. Every sentence carries meaningful information, and the examples are illustrative without being redundant. It's appropriately sized for the tool's simplicity.

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 low complexity (two optional parameters, output schema present), the description fully covers the essential aspects: what it does, what it returns, how to refine results, and how the output connects to other tools. The output schema handles return structure, so the description doesn't need to explain that further.

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 described. The description adds practical guidance by giving example query values ('inflation', 'trade', 'government') and explaining the filter's scope against id, name, and description. This goes beyond the schema's literal parameter descriptions and helps the agent construct effective queries.

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: 'List or search the IMF's datasets'. It also distinguishes itself from sibling tools by noting it returns the dataset id to pass to get_data and search_indicators, making its role as a discovery entry point 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?

The description implies when to use this tool (to discover datasets before using get_data or search_indicators) and provides concrete examples of query usage. It doesn't explicitly say when not to use it or name alternative tools, but the context is clear enough for an agent to infer the appropriate usage scenario.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds the scope ('caller's subscriptions') and the exact return fields (id, type, params, created_at, last_fired_at, fire_count), giving a clear behavioral picture without contradicting the annotations.

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

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

The description is two sentences with no wasted words. The first sentence states the purpose, and the second provides actionable usage guidance. It is front-loaded and appropriately sized for a simple read-only 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 read-only list tool with no output schema, the description fully explains what it returns and when to use it. The annotations cover safety semantics, and the description fills in the return format and use case, making it complete for an agent to invoke correctly.

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

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

The only parameter (include_inactive) is fully documented in the schema with a clear description and default. The tool description adds no additional semantic meaning beyond what the schema already provides, so the baseline of 3 is appropriate given the 100% schema coverage.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It also lists return fields and contrasts with subscribe/unsubscribe by saying 'Use this to review what you're monitoring before adding more or to find an id to cancel,' which distinguishes it from related tools.

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

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

The description gives clear context for when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It implies alternatives (subscribe/unsubscribe) but does not name them explicitly or provide a 'when not to use' statement, so it stops short of a 5.

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

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

All annotations are false, so the description carries the full transparency burden. It discloses the claim_token workflow, rate limit ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and expected impact ('team reads digests daily'). It also tells users what to avoid including in the message, such as pasting the end-user's prompt.

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 carries actionable information. It is well-structured: purpose first, then usage, exclusions, parameter guidance, follow-up behavior, and limits. Nothing is redundant, and the most important information is front-loaded.

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

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

Given the absence of an output schema, the description compensates by explaining what a filing returns (a claim_token) and how to later retrieve status. It covers all key decision points: when to use, when not to use, how to phrase feedback, what happens after filing, and rate limits. This is a complete guide 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?

Even though the input schema has 100% description coverage, the tool description adds important semantic context: it explains how claim_token is generated and later used, advises message length ('1-2 sentences typical'), and instructs users to describe issues in terms of Pipeworx tools/packs. This goes beyond individual schema 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?

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' a clear verb+object statement. It distinguishes itself from siblings by specifying it is for feedback on Pipeworx-provided tools and explicitly redirects feedback about other MCP servers elsewhere.

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 lists trigger conditions: bug, feature/data_gap, and praise. It also provides clear exclusions, stating that if the tool came from a different MCP server, you should 'file it with that server instead,' and offers a heuristic for ambiguous cases: 'Pipeworx tool names are the ones this connection lists.'

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

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

Annotations already declare the tool as read-only, non-destructive, idempotent, and open-world. The description adds valuable behavioral context by disclosing the data source (CF analytics-engine), privacy guarantee (no PII), and caching behavior (5min-1h depending on window), 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 compact and well-structured: a hook sentence, a returns summary, three bullet use cases, and a technical note. Every sentence serves a distinct purpose without 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?

The tool is simple (one optional parameter, no output schema) with strong annotations. The description covers what it returns, why it exists, data origin, privacy, and caching. This is a complete picture for an agent to decide and invoke correctly.

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

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

The input schema already provides comprehensive description of the single 'window' parameter with its enum values and explanation of short vs long windows. The description mentions the window in passing but adds only the caching dependency. Given 100% schema coverage, the description offers marginal additional parameter semantics, so a baseline 3 is appropriate.

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

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

The description uses a specific verb ('Returns') and resource ('top tools, top packs, and total call volume'), and clearly differentiates itself from sibling tools by focusing on aggregated behavior of other AI agents. The opening sentence adds a distinctive context that no other sibling provides.

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 concrete use cases under 'Useful for', giving clear guidance on when to invoke this tool. However, it does not mention exclusions or alternative tools, so it lacks the explicit 'when-not-to-use' guidance that would merit a 5.

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

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

The description goes far beyond the annotations (readOnly, openWorld, idempotent). It discloses the fill-check behavior (theoretical_edge_pp_at_book vs realizable_edge_pp, thin_legs, do-not-trade condition), the Jaccard similarity threshold (≥0.30), the placeholder filter (drops will-person-X / will-manager-Y, >20% returns null), and the response structure. No contradiction with annotations; the tool is read-only and non-destructive, and the description's 'signals' are informational, not executions.

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

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

The description is long but highly structured, with clear section markers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that aid scanning. The first sentence states the core purpose, and every subsequent sentence adds critical operational detail. For a complex tool with no output schema, this level of detail is warranted; there is no fluff or repetition.

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

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

Given the tool's complexity (3 modes, multiple internal checks, fill-risk integration, no output schema), the description is remarkably complete. It covers response structure (opportunities[], partition_check), failure modes (null arb signal, realizable_edge_pp ≤ 0), alternate tool linkage, and even the `skipped_low_similarity` field. The 0 required parameters and rich annotations lower the bar, but the description still exceeds it by explaining all runtime behaviors.

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 schema already describes both parameters with 100% coverage, the description enriches them substantially. For `event`, it explains that it 'walks child markets, checks date-axis / threshold-axis ordering AND computes the partition_check,' with concrete slug examples. For `topic`, it details the cross-event scanning, flattening, and comparator behavior. It also notes full Polymarket URLs are accepted, which is not explicitly in the schema. This goes beyond the baseline and adds meaningful context for correct usage.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly distinguishes it from siblings like polymarket_edges or polymarket_fill_risk by naming the exact method and scope. It also outlines three distinct modes (trending_scan, event, topic), each with a clear purpose.

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

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

Explicit usage guidance is provided: 'Call with NO args for a trending_scan, pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It recommends `event` for a specific market, explains what cross-event mode catches that single-event misses, and even directs users to `polymarket_fill_risk` for custom sizing. This leaves no ambiguity about when to use this tool versus alternatives.

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

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

The description goes far beyond the annotations, disclosing response structure (by_segment, fed_candidates, _diagnostics), edge calculation details (net of slippage, Kelly caps), the 24h-move warning, and the 1h KV caching behavior. This gives the agent a detailed understanding of what to expect, especially since no output schema is present.

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

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

The description is a dense wall of text with all-caps segments and implementation details (e.g., 'lognormal barrier from 90d FRED log-returns', 'GDELT 7d/21d article-volume ratio') that are not necessary for selecting or invoking the tool. While it is organized, it is not concise and may overwhelm the agent with too much internal specification.

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

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

With no output schema, the description fully compensates by detailing the response top-level fields (by_segment, fed_candidates, _diagnostics) and per-opportunity attributes (edge_pp_net, kelly_fraction, market.liquidity). It also explains the reasoning behind Fed bet exclusion and the purpose of diagnostics, making the tool's behavior complete and understandable.

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

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

The input schema already provides 100% coverage with detailed descriptions for all 9 parameters, so the baseline is 3. The tool description adds a concise summary of tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) but does not add significant new meaning beyond what the schema already states.

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

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

The first sentence clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb ('Scan') and resource ('Polymarket markets'), and the extensive detail about model families and response segments distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 frames the tool for 'what should I bet on today' and notes that agents discover opportunities 'without paging hundreds of markets.' It also provides caveats such as the unreliability of Fed signals, giving clear context. However, it does not explicitly name alternative sibling tools or state when not to use it, so it stops short of a 5.

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

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

The description discloses numerous behavioral traits beyond the annotations: the 60-day snapshot TTL limit, the dependency on snapshotting being enabled, data gaps meaning 'nobody scanned that day', and decay computed from daily closes not intraday. It also details the exact response fields and how edge_pp_net is signed. No contradictions with annotations.

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

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

The description is dense but every part earns its place. It is front-loaded with the core purpose, then systematically covers args, response structure, and limits in labeled sections. Despite length, it is efficiently organized for parsing.

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 read-only telemetry tool with no output schema, the description completely specifies the return value shape (`tracked[]`, `expired[]`, `snapshot_dates[]`) and key limitations. Combined with the rich annotations, the agent has everything needed 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 description coverage is 100%: both `days` and `window` have full descriptions. The description adds a bit of context (e.g., `window` meaning 'snapshot family', default/max values) but these mostly mirror the schema. It does not add substantial semantic meaning beyond what the schema already provides.

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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from the raw snapshot tool (polymarket_edges) by focusing on time-series trends and decay.

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: it tells the agent when this tool is appropriate ('a fresh wide edge and a 3-week-old wide edge are different trades') and what question it answers. It does not explicitly name an alternative tool to use instead, but the sibling list and the focus on persistence/decay make the distinction 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 provide readOnlyHint=true and destructiveHint=false. The description complements this by detailing what the tool computes (walks the ladder, returns top_of_book, VWAP, etc.) and warns about 'forced_directional_risk.' It does not explicitly state 'does not place orders,' but the 'check' framing plus annotations make the read-only nature clear. No contradiction.

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

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

The description is long but well-structured with clear mode separators (SINGLE-MARKET, BASKET) and a final usage directive. It is front-loaded with the core purpose. Every sentence adds value, though it could be tightened by moving some detail to output descriptions. Still, for a two-mode tool, the length is justified.

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

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

With no output schema, the description enumerates all significant return fields for both modes, explains the interpretation of size_usd, and gives concrete usage criteria. It covers prerequisites (requires market or event) and the key risk rationale. This is 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?

Although schema coverage is 100%, the description adds significant meaning: clarifies that `market` and `event` are mutually exclusive modes, explains the default behavior for `side` in basket mode (auto from partition sum), and interprets `size_usd` differently for buys vs sells and single-market vs basket. This goes well beyond the schema's short descriptions.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this from sibling tools like polymarket_arbitrage and polymarket_edges by framing it as a pre-trade risk check, with explicit mode distinctions (single-market vs basket).

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the alternative/fallback rationale (partial fills convert arbs into directional risk) and names the exact sibling signals that require this check.

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 readOnly/idempotent hints, the description discloses critical behavior: compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0 vs 0), temporal_alignment semantics (aligned:false means meaningless spreads), and how skipped_cross_type/subtype counters work. This is exceptional transparency for a complex cross-venue tool.

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

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

The description is long but each section serves a purpose: purpose, modes, response structure, and safety fields. It is front-loaded with the core concept and then details necessary caveats. Dense but not wasteful.

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

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

Given no output schema, the description thoroughly explains the response shape (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and all edge cases. An agent can confidently invoke and interpret results based solely on this description.

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

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

Schema coverage is 100% with descriptions for all three params. The description adds significant meaning by explaining the two modes, that explicit ticker/slug override topic mappings, and how the topic list relates to pre-mapped shortcuts, enriching the raw schema.

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

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

The description clearly states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question, with a specific verb+resource+scope. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing specifically on the Kalshi–Polymarket spread and its bet-shape equivalence checks.

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

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

Explicitly describes two usage modes (topic shortcuts vs explicit ticker/slug), explains when each is appropriate, and cautions that pre-mapped topics often return compatibility_warnings and are not necessarily tradeable. It does not name alternative tools for exclusion but gives clear contextual 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 indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: the scoping to the agent's identifier (IP hash, etc.) and the behavior of listing all keys when the key is omitted. This gives the agent useful expectations not captured by the annotations.

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

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

The description is three sentences, front-loaded with the primary action, followed by use cases and scoping. Every sentence adds value without redundancy or fluff, making it highly efficient.

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

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

For a simple tool with one optional parameter, full schema coverage, and strong annotations, the description covers the two usage modes, scoping, and complementary tools. There is no output schema to explain, and the description implicitly conveys return behavior (value vs. list). It is complete for this low-complexity tool.

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

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

The input schema already provides 100% coverage with a clear description of the 'key' parameter ('Memory key to retrieve (omit to list all keys)'). The description repeats this and adds examples of stored values, but it doesn't introduce new parameter-level details such as key format constraints or naming conventions. Baseline 3 is appropriate when schema covers everything.

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

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

The description clearly states a specific action ('Retrieve a value previously saved via remember') and an alternative mode ('list all saved keys'), immediately distinguishing it from sibling tools like remember and forget. It identifies the resource and the exact behavior, 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?

The description explicitly says when to use the tool ('look up context the agent stored earlier') and provides concrete examples (ticker, address, research notes). It names complementary tools ('Pair with remember to save, forget to delete'), which clarifies the workflow and differentiates from 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?

The description discloses mark_read:true mutates state ('flag returned events read'), which directly contradicts the annotation readOnlyHint=true. Per the rubric, any contradiction forces a score of 1. This is an annotation contradiction.

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

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

Three sentences, front-loaded with a clear purpose, and every sentence adds value including behavioral notes and alternative access. No fluff or repetition.

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

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

Despite no output schema, the description covers return fields, filtering options, the mark_read side effect, and even gives a REST alternative. With all parameters documented in the schema, this is complete for a read-like tool with a notable state-modifying option.

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

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

Schema coverage is 100%, but the description adds value with concrete examples ('sec_8k') and clarifies ISO timestamp format for 'since'. It also explains the effect of mark_read, going beyond the schema.

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

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

The description clearly states the verb ('Pull') and resource ('fired events from your subscription feed'), and distinguishes it from sibling tools like list_subscriptions by focusing on alert delivery. It also specifies return fields, making it unambiguous.

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

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

The description indicates this is for polling ('Polls work fine') and notes an alternative access method for scripts/dashboards, providing practical context. However, it doesn't explicitly contrast with sibling tools like ask_pipeworx or list_subscriptions, so it's not a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral detail: fan-out to multiple sources, GDELT→GNews fallback on rate limits/5xx, USPTO soft-fail due to API sunset, and the return structure (changes[], total_changes, citation URIs). This is rich context 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 dense but well-organized: it opens with query examples to convey intent, then explains the fan-out sources, parameter semantics, output shape, and alternatives. Every sentence adds value, and the length is justified by the tool's multi-source complexity. No filler or redundancy.

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

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

Given the tool's complexity (three data sources, fallback logic, parameter flexibility) and no output schema, the description is remarkably complete. It explains what the tool returns, how the window parameter works, what sources are consulted, fallback behavior, edge cases (USPTO sunset), and how this tool differs from a likely sibling (entity_profile). Nothing critical is missing.

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

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

Schema covers 100% of parameters with descriptions, but the tool description adds significant extra semantics: it explains 'since' accepts ISO dates or relative shorthand including examples ('7d', '30d', '3m', '1y'), recommends '30d'/'1m' for typical monitoring, and clarifies that 'value' can be a ticker or zero-padded CIK. These details enhance usability beyond the schema.

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

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

The description clearly states the tool's purpose: a change feed for a company over a time window, covering filings, news, and patents. It distinguishes itself from siblings by explicitly contrasting with entity_profile (static profile) and providing example queries that signal its intended use case.

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

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

Provides explicit when-to-use guidance via natural language examples like "What's new with X" and "latest on Y". It also names the alternative tool (entity_profile) and explains when to prefer it, which goes beyond mere implication and gives clear decision criteria.

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

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

The description adds meaningful behavioral context beyond the annotations, such as persistence duration ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours') and scoping ('by your identifier'). It does not contradict the idempotentHint, and it does not explicitly state overwrite behavior for duplicate keys, but the added context is valuable.

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

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

The description is four sentences, front-loaded with the primary purpose, followed by usage context, storage details, and related tools. It is concise and every sentence contributes, though slightly longer than strictly necessary for a simple write operation.

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 two-parameter tool without an output schema, the description covers purpose, usage, persistence behavior, and sibling relationships. It is complete enough for an agent to invoke correctly; the only minor gap is lack of explicit return value expectation, which is rarely needed for a save 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 coverage is 100% with both `key` and `value` described and exemplified. The description reinforces the purpose of parameters via examples but does not add new semantic details beyond what the schema already provides, meriting the baseline score.

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

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

The description states a specific verb and resource: 'Save data the agent will need to reuse later.' It clearly distinguishes from siblings by mentioning pairing with `recall` to retrieve and `forget` to delete, making the tool's 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 provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, target address, user preference). It names complementary alternatives (`recall`, `forget`) but does not explicitly state when-not-to-use, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds significant behavioral context beyond these: it explains that the tool cascades through multiple lookup endpoints internally, that it degrades gracefully (if GLEIF or OpenFIGI is unavailable, EDGAR identifiers still return), and that unresolved identifiers are explicitly stated rather than omitted. This provides rich transparency about edge cases and internal behavior, fully satisfying the dimension.

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 informative but verbose, spanning multiple paragraphs. While it is well-structured with examples, supported types, and behavior notes, it could be more concise. The first sentence effectively front-loads the purpose, but subsequent details about graceful degradation, identifier labels, and source attribution could be condensed or moved to a secondary section. It is not wasteful, but it exceeds the optimal length for quick scanning.

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

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

Given the tool's complexity (two entity types, multiple data sources, graceful degradation, explicit unresolved identifiers), the description is remarkably complete. It explains what each type returns, how sources are labeled, fallback behavior, and even the internal cascading lookup. Although there is no output schema, the description effectively describes the return format and edge cases. It leaves no major gaps for an agent to understand how to use the tool correctly.

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

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

Schema coverage is 100% (both parameters have descriptions). The description goes far beyond the schema by explaining the semantics of each parameter in context: for 'type' it details what identifiers are returned for each entity type (e.g., for 'company': CIK, ticker, LEI, FIGI with sources), and for 'value' it lists acceptable inputs (ticker, CIK, ISIN, company name) and explains special behavior like ISIN-to-LEI mapping. This adds substantial meaning that the bare schema cannot convey.

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 clear examples of user queries ('What's the ticker for...', 'find the CIK for...') and immediately states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It explicitly distinguishes this tool from siblings by saying 'Use FIRST whenever you have a name but need an ID,' positioning it as the primary name-to-ID resolver. The supported types and their outputs are specified, making the purpose highly specific and actionable.

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 the tool: 'Use FIRST whenever you have a name but need an ID.' It also gives concrete examples of query types and supported entity types. However, it does not explicitly state when NOT to use this tool or compare it directly to siblings like 'entity_profile' or 'search_within.' The guidance is strong but lacks explicit exclusion criteria, which would push it to a 5.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds that it 'Probes each entity with ai_visibility_check,' ranks by score, and returns a ranked list with specific fields. This explains the underlying process and output structure, going beyond the safety annotations. No contradiction.

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

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

The description is compact—three sentences, each earning its place: what, how, and when to use. Front-loaded with the core purpose, it wastes no words.

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

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

Given the lack of an output schema, the description explicitly states the return format ('ranked list with score, confidence, signal density per entity'). It also covers process, use case, and relies on schema for parameters—adequate for a complex multi-entity 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 covers all four parameters with descriptions (100% coverage), so the description is not burdened to add param semantics. It mentions 'your brand + N competitors' but that's already in the schema's 'entities' description. 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 a specific action—'Compare AI visibility across multiple entities side-by-side'—and distinguishes itself from sibling `ai_visibility_check` by emphasizing multi-entity comparison, ranking, and output. The verb 'Compare' + resource 'AI visibility' + scope 'multiple entities' makes it unambiguous.

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

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

The description provides an explicit use case ('competitive AI-marketing audits') with an illustrative question, which tells agents when to choose this tool over single-entity checks. It does not mention when not to use it or name alternative tools, but the context is 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 indicate read-only and idempotent behavior, but the description adds rich context: it fans out across services, handles partial failures gracefully, may take 5-30s for first bundlephobia measurement, and returns 'sources_failed' on timeout. These are behavioral insights 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 dense but every sentence adds value: purpose, usage, output fields, ecosystem scope, and failure behavior. It is front-loaded with the main point and ends with caveats, making it efficient and well-structured for its complexity.

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

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

For a complex composite tool, the description covers the key context: what sources are consulted, what output is expected, how failures are handled, and performance characteristics. Combined with the schema and annotations, the agent has a full picture of when and how to use it.

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 both 'package' and 'version' are already well documented. The description reinforces that package is an npm name and version defaults to latest, but adds no new semantics beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: a composite check to decide 'should I add this npm package to my project'. It specifies the resources (deps.dev, bundlephobia) and the output summary block, making it distinct from sibling research tools.

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

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

Explicit use cases are provided ('is X safe / popular / small', 'what does adding lodash cost me'), and it clearly distinguishes when NOT to use it (non-NPM ecosystems fall under deps.dev:version directly). This gives strong guidance on when to invoke the tool and when to use an alternative.

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

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

The annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description doesn't need to repeat that. It adds useful behavioral context beyond annotations: the effect of a query (filtering codes) and the behavior when no query is provided (returns dimension list and a sample of codes). No contradictions with annotations.

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

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

The description is two sentences long, front-loaded with the core purpose, and includes a concrete example. Every sentence contributes meaning, and there is no redundancy with the schema or annotations.

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

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

Given the tool's simplicity (2 parameters, output schema present, strong annotations), the description fully covers what an agent needs to know: what it discovers, how to use it before get_data, and the difference between query and no-query behavior. No 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the query parameter's filtering behavior and illustrating with an example (search_indicators({dataset:"CPI", query:"united states"}) finds COUNTRY=USA). It also clarifies the effect of omitting the optional query parameter, going slightly beyond the schema's property 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 states exactly what the tool does: 'Discover what a dataset accepts: its dimension names in key order, and the codes available for each, filtered by query.' It uses a specific verb (discover) and resource (dataset dimensions/codes), and clearly differentiates from get_data by saying 'Use this before get_data'.

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 context: 'Use this before get_data' and gives a concrete example with the CPI dataset. This tells the agent when to invoke it (as a preliminary exploration step) and distinguishes it from the data-fetching sibling 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?

Although annotations already indicate read-only, idempotent, and open-world behavior, the description adds substantial technical disclosure: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and a 200K-char cap with truncation flagging. It also clarifies that results include offsets for verification, which is valuable behavioral context 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 four sentences, each earning its place: purpose, use case, integration, and technical detail. It is front-loaded with the core function and avoids redundancy with the schema or annotations. No fluff or digressions.

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

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

For a tool with no output schema, the description thoroughly explains what to expect: top-N passages, character offsets, and similarity scores. It also covers use cases, pairing with ask_pipeworx_grounded, and edge cases like truncation. Despite the absence of an output schema, the agent has enough context to invoke and interpret results correctly.

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

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

The schema already covers all three parameters at 100% coverage, so the baseline is 3. The description adds value by providing concrete examples for 'text' (SEC 10-K, article, tool result) and 'query' (supply-chain risk, fiscal year revenue), and it reinforces the character cap mentioned in the schema. This elevated semantics slightly above the 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,' using a specific verb and resource. It clearly states inputs (text and natural-language query) and outputs (top-N passages with character offsets and similarity scores), and distinguishes itself from siblings by emphasizing it works on a previously fetched record rather than external sources.

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: 'Use when the record is too big to cram into the prompt.' It also explains how it pairs with ask_pipeworx_grounded for grounded generation. However, it does not list explicit when-not-to-use scenarios or alternative tools beyond this pairing, so it falls just short of a 5.

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

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

The description discloses substantial behavioral traits beyond annotations: it requires a Pipeworx OAuth account, explains feed/email/SMS/webhook delivery channels, notes SMS verification and rate caps, and details webhook HMAC signing and auto-disable behavior. These details are not in the annotations and meaningfully guide correct invocation. No contradiction with annotations.

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

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

The description is dense and front-loaded with the core purpose, and every section covers necessary aspects (auth, types, delivery). It is long but well-structured with commas and semicolons. A minor deduction because it repeats some schema details (e.g., SMS cap) and could be more scannable with bullet points, but overall it is efficient.

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 (5 subscription types, nested params, optional delivery object, no output schema), the description is thorough: it explains the return value (subscription id), enumerates all supported types with key parameters, details delivery options, and covers edge cases like webhook secret and auto-disable. No critical information appears 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 input schema already has 100% coverage with detailed descriptions for all parameters. The description adds a few extra examples and clarifications (e.g., 'items:["5.02"] = officer change' and 'topic:"fed"'), but largely overlaps with schema content. This exceeds the baseline of 3 for high schema coverage, but does not warrant a 5 since much of the parameter guidance is already present.

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 'Create a proactive monitoring subscription to a live-data event stream,' which includes a specific verb and resource. It clearly distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation and monitoring. It also states the return value, removing ambiguity.

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

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

The description provides clear context for when to use the tool: for proactive monitoring subscriptions, and it mentions prerequisites like an OAuth account. It also hints at complementary tools by referencing 'pull via recent_alerts or GET registry.pipeworx.io/alerts.json.' However, it does not explicitly state when not to use it or name direct alternatives, 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 declare readOnly, openWorld, idempotent, and non-destructive behavior, so the bar is lowered. The description adds useful context about the return value (category-bucketed example questions with exact tool + argument shape) and call variations (no args vs topic), enhancing transparency 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 front-loaded with user intents and structured as a single coherent paragraph. Each clause adds value, from the onboarding purpose to the return format and call variants. While not as brief as possible, it earns its length given the tool's onboarding role.

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 by clearly explaining what the tool returns: category-bucketed example questions each with the exact tool + argument shape. It also covers usage modes (no args vs topic) and provides examples of focus areas, making it sufficiently complete for an agent to invoke correctly without further documentation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the topic values from the schema and adds a brief usage example, but it does not add substantial new meaning beyond what the schema already provides (e.g., 'Omit for a cross-category spread' is already in the schema).

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

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

The description uses a specific verb ('Returns') with a clear resource ('category-bucketed example questions') and differentiates from siblings by positioning itself as the 'onboarding entry point' and 'use this FIRST'. It also specifies the meta-tools it can teach, distinguishing it from ask_pipeworx and discover_tools.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also lists example user intents ('what can I ask', 'getting started'), giving clear guidance on triggering scenarios without needing to name exclusions.

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

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

The description reveals key behaviors beyond the annotations: ownership enforcement and that the row is deactivated rather than deleted, preserving historical events via recent_alerts. This clarifies the non-destructive nature and data-retention implications in a way the annotations alone do not fully convey.

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

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

Three short, front-loaded sentences deliver the action, constraint, and side effect with no redundant wording. Every sentence adds meaningful information.

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

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

For a simple mutation tool with one well-documented parameter, rich annotations, and no output schema, the description fully covers purpose, scope, and side effects. It does not describe return values, but that is not essential given the schema and annotation coverage.

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

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

The input schema already covers 100% of the parameter (id) and describes it as a UUID returned by subscribe. The description merely restates the id requirement without adding new semantics, 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 opens with 'Cancel a subscription by id', using a specific verb and resource that clearly distinguishes it from sibling tools like subscribe, list_subscriptions, and recent_alerts. It immediately conveys the tool's core function without ambiguity.

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

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

The phrase 'Cancel a subscription by id' directly states when to use the tool, and the ownership constraint ('you can only cancel your own subscriptions') adds practical context. However, it does not explicitly name alternatives or state when not to use it, though sibling context makes the intended usage obvious.

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 a safe read-only, open-world, idempotent operation. The description adds crucial semantic details: could_not_verify means the check did not happen and must not be treated as evidence, while unsupported means no source was found. This prevents misinterpretation of verdicts and 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 fairly long but every section earns its place: trigger phrases, pipeline routing, verdict semantics, and a caution about misinterpretation. It is front-loaded with examples and structured logically, though slightly dense.

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

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

There is no output schema, so the description carries the burden of explaining return values. It lists all verdict categories, the actual value with citation, reasoning, and the verification_error structure. It could include a concrete example output, but it covers the essential information for correct use.

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

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

The input schema provides 100% coverage with detailed descriptions for both claim and tolerance_pct, including the tolerance overriding behavior and defaults. The tool description does not add new parameter meaning beyond what the schema already gives, so the baseline of 3 applies.

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

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

The description clearly identifies the tool as natural-language claim verification with explicit trigger phrases like "fact check" and "verify the claim that". It states the output is a verdict, distinguishing it from general ask tools.

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

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

It explicitly states "Use whenever the agent needs to check whether something a user said is factually correct." It also describes the two pipeline paths (SEC EDGAR for financial claims, grounded pipeline otherwise) and notes it replaces 4–6 sequential calls, giving clear guidance on when to use.

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