Spotify

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

Annotations already declare readOnlyHint and idempotentHint, so the bar for additional transparency is lower. The description adds valuable context: the default model is free, Anthropic calls are paid directly by the user, and the return structure includes per-model {score, confidence, signals, raw_response} plus a combined view. This goes beyond the annotations without contradicting them.

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

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

The description is compact and well-structured: it front-loads the core purpose, then explains model options and cost, then lists the return structure, and finally gives example use cases. Every sentence earns its place with 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?

With no output schema, the description compensates by describing the per-model response fields and combined view. It covers the essential invocation details (entity, models, API key, context) and provides enough context for an agent to decide when to use it. It doesn't mention rate limits or error handling, but these are not critical for a read-only probe tool with openWorldHint.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond the schema by clarifying that 'models' defaults to 'workers-ai', that '_apiKey' is only needed for Anthropic and is passed straight to api.anthropic.com with cost implications, and that 'context' disambiguates common names. These details add behavioral meaning beyond the raw 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 uses a specific verb ('Probe') and resource ('one or more LLMs') and clearly states the outcome ('score visibility (0-100) per model'). It distinguishes itself from sibling tools like ask_pipeworx or deep_research by targeting AI-marketing audits, pre-launch brand checks, and competitive monitoring, so the agent can differentiate it from alternatives.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains how to choose models (default free Workers AI, or BYO Anthropic key). It lacks explicit exclusions or named alternatives (e.g., 'use scan_competitor_ai_presence for...'), so it stays at a 4 instead 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/openWorld/idempotent annotations, the description discloses meaningful behavior: it independently selects among thousands of tools, fills arguments automatically, and returns structured answers with stable citation URIs. It also sets expectations that it should be used even when web search could answer, which is valuable non-obvious guidance.

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

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

The description is long but information-dense and front-loaded with the most important guidance, 'PREFER OVER WEB SEARCH'. Every section—domains, routing behavior, trigger phrases, examples, alternatives—serves a purpose; only slight redundancy between 'START HERE' and the earlier 'Use whenever' statement prevents a perfect score.

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

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

For a tool with a single required natural-language parameter, the description covers input, routing behavior, output style, citations, and the main alternative. The remaining gaps are minor: it does not disambiguate against ask_pipeworx_beta or ask_pipeworx_grounded, and it does not describe what happens when no source matches the question.

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 100% of parameters: all six are aliases for the same question string. The description adds value beyond the schema by showing acceptable question patterns and six concrete examples, clarifying that the input is a broad natural-language fact-finding query rather than a structured command.

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 precise mission: prefer over web search for authoritative current/historical data, then explains that it routes to the right tool among 5,798 tools and returns structured answers with pipeworx:// citation URIs. This is a specific verb-plus-resource definition that clearly distinguishes it from generic search and deep_research.

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

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

The description explicitly tells the agent when to prefer this tool, provides trigger phrases like 'what is', 'look up', 'find', 'get the latest', and gives concrete example questions. It also names an alternative, deep_research, for broad/multi-part questions, and clarifies that breaking-news routes through ask_pipeworx already.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior; the description adds beta status, live candidate-routing experiments, the current no-active-candidate state, and 'falls back to nothing' to prevent the assumption of a stable fallback. This is significant behavioral context beyond what the 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?

Four dense sentences front-load identity, then cover status, usage, and fallback behavior without filler. Every sentence contributes distinct information, and the structure makes the current parity and experimental nature immediately visible.

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

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

The description sufficiently covers what the tool is, how to invoke it, current behavior, and that it is a full working router with no fallback. It relies on ask_pipeworx for output shape, but explicitly states the response shape is identical; it only slightly under-specifies stability risk for production use.

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

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

Schema coverage is 100% and the schema already describes question, aliases, chaining preference, and profile with meaningful descriptions. The tool description adds only that the arguments match ask_pipeworx, so it provides no parameter-level value beyond the high-coverage schema; baseline 3 is appropriate.

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

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

The description opens with 'Beta version of ask_pipeworx' and explicitly describes it as an identical universal router with the same tools, arguments, and response shape. It clearly ties the tool to its stable sibling and states that it currently matches ask_pipeworx exactly, so an agent can tell what the tool does and how it differs.

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 says 'Use it exactly like ask_pipeworx when you want the newest routing' and mentions stable-router comparison for merge decisions, giving a clear selection condition. It does not explicitly state when not to use it, such as for stable/production calls, so it stops just short of full exclusion guidance.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses the internal routing over 5,798 tools, the constraint of using ONLY the tool result, the exact success/refusal response shapes, and the extra LLM call cost. There is no contradiction with annotations.

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

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

Though longer than average, the description is front-loaded with the core mode definition and each sentence carries distinct value: mechanism, return contract, refusal contract, usage rule, and cost trade-off. 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?

Given the absence of an output schema and the tool's complex internal routing, the description is remarkably complete: it defines what success returns, lists all refusal reasons, specifies when to prefer the grounded mode over ask_pipeworx, and warns about the extra call cost. Agents have enough 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?

Schema description coverage is 100% and the schema already documents the question parameter in natural language with its aliases. The tool description adds usage context but no additional parameter-level semantics, so the baseline 3 applies.

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

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

The description names a specific behavior: a hallucination-resistant answer mode that routes through Pipeworx tools, fetches data, and extracts answers only from the tool result. It explicitly separates itself from ask_pipeworx ('Same routing as ask_pipeworx') while clarifying a distinct grounded mode, so agents can tell them apart.

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

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

It gives explicit when-to-use guidance: quote/cite/act-on or no-fabrication contexts such as financial verdicts, legal claims, medical lookups, and public statements. It also states when not to use it — casual lookups — and points to ask_pipeworx as the cheaper alternative, making the trade-off concrete.

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

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

The description goes far beyond annotations, detailing extensive behavioral traits such as classification, fan-out to data sources, response shapes, resolver contract, parent_event extraction, news fallback mechanisms, safety short-circuiting, and resolution-rule risk handling. This adds significant context beyond the readOnly/openWorld/idempotent hints.

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

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

The description is front-loaded with the purpose and is well-structured using labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). However, it is lengthy and contains redundant examples and details, which could be trimmed for conciseness without losing crucial information.

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

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

With no output schema, the description thoroughly explains return values, including result.market, result.analysis, result.evidence, resolver contract fields, parent_event, and status codes. It also covers edge cases like low-confidence matches, closed markets, and wide spreads, making it highly 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 description coverage is 100%, and the description does not add material meaning beyond the schema for market, depth, or include_raw. The description provides examples and fan-out context, but these are already implied by the schema. Per the rubric, a baseline of 3 is appropriate when schemas fully document parameters.

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

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

The description clearly states the tool's primary function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and scope (pulling relevant Pipeworx data), distinguishing it from sibling tools like ask_pipeworx or polymarket_edges by focusing on bet-specific research with fan-out.

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 recommends use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z', providing clear usage context. However, it does not explicitly state when not to use the tool or recommend alternative sibling tools for different scenarios, so it lacks exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context beyond annotations: data sources (SEC EDGAR/XBRL, FAERS), fiscal-year handling (AAPL Sep, NVDA Jan), sorting by primary metric, and return format (paired data + citation URIs). No contradiction.

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

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

The description is longer than typical but every sentence is informative and purpose-led. It opens with trigger phrases, states the core function, then details type-specific behavior, sorting, and return format. It is somewhat dense but avoids fluff, earning a high score while not being maximally streamlined.

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

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

No output schema exists, so the description must explain return values. It mentions 'paired data + pipeworx:// citation URIs' but could specify the exact response structure or units. However, with only two well-documented parameters and rich detail on data sources, sorting, and fiscal-year handling, it is sufficiently 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?

Schema coverage is 100% and parameter descriptions are clear. The description adds semantic depth by explaining what each type pulls: company gets revenue, net income, cash, long-term debt; drug gets FAERS, FDA approval counts, trial counts. This exceeds the schema's enum-only descriptions, though it doesn't need to compensate for missing schema info.

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+resource: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It includes multiple natural-language triggers ('X vs Y', 'which is bigger', 'rank these companies') and distinguishes from siblings by noting it replaces 8–15 sequential single-pack 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 directs when to use: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It lists concrete query patterns that should route here and clarifies the scope (comparing entities, not single lookups), giving clear context without explicitly naming alternatives but implying the contrast.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context beyond annotations: it explains the parallel decomposition into facets, the gap-recovery hops, contradictions[] scan, the guarantee never to invent findings, the semantic excerpting (not head-truncation), the citation_uri fetchability guarantee, and the 15-90s latency expectations. It also explicitly says it does NOT do open-web search — a critical behavioral trait. No contradictions with annotations.

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

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

The description is dense and information-rich, front-loading the critical account requirement and the alternative tool first, then the core purpose, then behavioral details. It covers many important traits without being padded. However, it is long and contains some parenthetical density (e.g., nested parentheticals about depth tiers and the lengthy cite/recovery clauses), so it slightly taxes reading. Still, every sentence earns its place — very few wasted words.

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

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

For a tool with 2 parameters, 100% schema coverage, and rich annotations, the description covers everything an agent needs to decide when to invoke it: use cases, prerequisites (account/tier), alternatives, behavior, latency, output traits, and citation guarantees. There is no output schema, so the description appropriately explains the findings packet. The only minor gap is that the exact response format is described at a high level ('findings packet') but the details are sufficiently specified for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes well beyond the schema by explaining what 'depth' actually means behaviorally: quick=3 facets/single hop, standard=3 facets with a gap-recovery hop + contradictions[] scan, thorough=6 facets with a full iterative hop + contradiction scan, and cost implications (paid). It also clarifies that the question parameter is meant for broad/multi-part natural language. This adds real semantic value beyond the schema's enum and type definitions.

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

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

The description clearly identifies the tool as a grounded multi-source research tool across 1,517 structured data sources, explicitly distinguishing it from open-web search. It names the exact verb/resource (decomposes questions into facets, routes to tools in parallel, returns findings packet). The sibling differentiation is strong: it explicitly contrasts with ask_pipeworx for signed-out users and mentions it is not open-web search, making it easy to distinguish from sibling tools like search and ask_pipeworx.

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

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

The description provides explicit when-to-use guidance: best for broad/multi-part questions over structured data, with concrete examples. It explicitly states when NOT to use it ('For a single lookup use ask_pipeworx instead') and names the alternative. It also specifies the account requirement and which depth tier needs a paid plan, providing clear context for selection.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context beyond that: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This explains the return behavior and the 'no second lookup' convenience. It does not mention rate limits or auth, but with annotations covering safety, this is solid.

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 covering purpose, usage, and return structure. The sentence listing domains is long but informative; it could be trimmed, but it earns its place by showing the breadth of covered topics. Front-loaded with the primary purpose, so it is efficient and well-structured.

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

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

For a meta-tool with no output schema, the description is remarkably complete. It explains when to use it, what it returns (top-N tools with schemas and examples), and that results are directly callable. Given the large sibling set, the 'Call this FIRST' guidance is crucial and provided. No obvious 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 description coverage is 100%, so the baseline is 3. The description adds context that the 'query' parameter should be a natural language description of the data or task, and mentions 'top-N' which aligns with the 'limit' parameter. However, it does not go beyond what the schema already states about aliases and defaults, so no extra credit beyond 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 begins with a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes itself from siblings by focusing on tool discovery rather than data access, and even states 'Call this FIRST when you have many tools available.' The domain list (SEC filings, FDA drugs, etc.) further clarifies scope.

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

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

Explicit usage guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent when to choose this tool over the many siblings, though it could mention what not to use it for.

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/openWorld annotations, the description discloses soft-failure behavior for the USPTO patents source, a GDELT-to-GNews fallback, per-source sources_used/sources_failed tracking, and the resolved:false behavior for private companies. It also clarifies that an empty FDA section is expected for companies without biologics. This greatly exceeds annotation coverage.

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

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

The description is front-loaded with trigger phrases and the core 'one parallel call' concept, and each behavioral detail is useful given the tool's complexity and lack of an output schema. It is quite long and somewhat dense, and it repeats some schema-level parameter details, so it is not maximally concise, but it earns its length.

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

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

With no output schema, the description carries full responsibility for explaining return structure, and it does so thoroughly: CIK, filings, fundamentals, patents, contracts, FDA products, hiring, news, LEI, and source tracking. It also covers input variants, resolution behavior, private-company handling, and expected empty results. Nothing essential is missing.

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

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

The input schema already provides 100% parameter coverage, including the interchangeable type enum and the ticker/CIK/company-name value formats. The description restates these forms and adds a small amount of output behavior context, but it does not meaningfully add net parameter 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 identifies the operation: producing a full cross-source profile of a US public company in one parallel call, with multiple trigger-phrase examples. However, it does not explicitly differentiate itself from named siblings such as resolve_entity, compare_entities, or deep_research, so the distinction from alternatives is implied rather than stated.

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

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

The description explicitly instructs the agent to ALWAYS PREFER this tool over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view. It also provides important routing context: empty sections are expected and not failures, and private companies resolve to resolved:false with notes. This gives clear when-to-use and when-not-to-misinterpret guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds no new behavioral traits beyond the act of deleting, but it is consistent. Minimal additional context is provided, so a 3 is appropriate.

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

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

Two-sentence description, front-loaded with purpose and immediate usage context. Every word earns its place, with no redundancy or filler.

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

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

For a simple single-parameter tool with strong annotations, the description fully covers purpose, usage, and relation to siblings. No output schema is needed, and the description is sufficient on its own.

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

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

Schema description coverage is 100% for the single 'key' parameter, which is described as 'Memory key to delete'. The description merely says 'by key', adding no extra semantic detail beyond the schema.

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

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

The description uses a specific verb ('Delete') and resource ('previously stored memory by key'), clearly distinguishing it from siblings like remember and recall. It's direct and unambiguous.

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

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

Explicitly states when to use (stale context, task complete, sensitive data) and names complementary tools ('Pair with remember and recall'). This is strong guidance for an AI agent.

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

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

The description discloses the core behavior: it 'fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format'. This adds meaningful behavioral detail beyond the annotations, which already indicate read-only and idempotent behavior. It also specifies the output as a single text blob, setting expectations for the response format.

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

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

The description is three sentences: the first states the core function, the second explains the process, and the third gives concrete use cases. Every sentence adds value, with no redundant filler. It is front-loaded with the primary purpose and reads clearly.

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 no output schema, the description is complete: it explains what the tool does, how it works (fetch, extract, emit), what the output looks like (single text blob), and why it is useful. No critical information is missing for an agent to select and invoke the tool effectively.

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

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

Schema coverage is 100%, so the parameters 'url' and 'max_links' are already fully documented in the schema. The description mentions 'any URL' and the purpose, but doesn't add syntax or format details beyond the schema. Per the baseline rule for high schema coverage, a score of 3 is appropriate.

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

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

The description clearly states the tool 'Generate a production-ready llms.txt file for any URL', specifying an exact verb, resource, and purpose. It differentiates itself from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on the specific output artifact (llms.txt) rather than broader AI visibility 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 provides explicit use cases under 'Useful for:', including getting a client's site indexed, drafting for one's own project, or auditing a competitor. It lacks explicit 'when not to use' guidance or alternative tool references, but the clear use cases make the intended context 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so safety is established. The description adds the return field list, which is useful but not a behavioral trait beyond what annotations and output schema already provide. No additional side effects or limitations are disclosed.

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

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

Two sentences, front-loaded with the core action, then a concise list of return fields. Every word earns its place; no filler.

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

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

For a simple fetch tool with full schema coverage, comprehensive annotations, and an output schema, the description provides a complete summary. It covers what the tool does, what it returns, and the optional filter—sufficient for an agent to select and invoke correctly.

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

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

Schema coverage is 100%—both album_id and market are described in the schema. The description mentions 'optional market filter,' which mirrors the schema's 'Market for availability' without adding new detail. 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 ('Fetch') and resource ('Spotify album by album_id'), clearly distinguishing it from sibling tools like get_track or get_artist. It enumerates the returned data, leaving no ambiguity about scope.

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

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

Clear context: this is the tool for fetching a full album by ID. It does not explicitly name alternatives or exclusions, but the album-specific scope implies when to use it. Lacks explicit 'use get_track for tracks' guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds no extra behavioral context like error handling, authorization needs, or special side effects; it only lists return fields, which are already in the output 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 a single, front-loaded fragment that efficiently communicates the tool's purpose and return contents without redundant words. Every element earns its place, making it appropriately concise.

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

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

For a simple read-only tool with full schema, annotations, and output schema, the description is nearly complete. It clearly conveys the return fields, and the title and sibling names provide enough context for selection. Missing explicit usage comparisons are the main gap, but given simplicity, the overall completeness is strong.

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 describes the single parameter (artist_id as 'Spotify artist ID'), so schema coverage is 100%. The description contributes no additional meaning or usage detail about the parameter, meeting the baseline for high coverage.

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

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

The description clearly identifies the resource (artist record) and lists key fields (name, genres, popularity, followers, images), distinguishing it from siblings like get_artist_top_tracks. However, it lacks an explicit verb like 'retrieve' or 'get', instead relying on the title to convey the action.

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

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

No explicit guidance is given on when to use this tool versus alternatives such as get_artist_top_tracks or get_album. The description merely states what the record contains, leaving the agent to infer applicability without clear context or exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds 'Spotify recommendation' as context, hinting that results come from Spotify's recommendation engine, but it does not disclose other behaviors like pagination or rate limits. Since annotations carry most of the burden, a score of 3 is appropriate.

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, focused sentence that communicates the core purpose without waste. It is front-loaded and easy to parse.

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 a simple read operation with comprehensive schema and annotations, plus an output schema exists. The description sufficiently covers the high-level purpose. It does not explicitly mention alternatives or exclusions, but the overall context is complete for a tool of this simplicity.

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

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

Schema description coverage is 100%, with both 'market' and 'artist_id' clearly documented. The description mentions 'market' but does not add additional semantic detail beyond the schema. 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 states the resource ('top tracks for an artist') and the scope ('in a market'), and the verb 'get' is implied by the tool name. It distinguishes itself from sibling tools like get_artist (artist details) and get_track (a specific track) by focusing on top tracks.

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 a clear context: use this to retrieve an artist's top tracks in a given market. It implies the use case but does not explicitly exclude alternatives or mention when not to use it. No alternatives are named, but the specific phrasing 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 declare this as read-only, idempotent, and non-destructive, so the safety profile is known. The description adds no extra behavioral context (e.g., errors, authentication, or rate limits) but also does not contradict the annotations.

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

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

The description is a single, front-loaded sentence that directly states the tool's purpose and enumerates the returned features. It is concise, with no unnecessary words or repetition.

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

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

For a simple tool with one parameter, rich annotations, and an output schema, the description adequately covers the essential information. It could mention limitations or usage scenarios, but the feature list combined with the schema makes it sufficiently complete 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?

The schema fully describes the only parameter (track_id as 'Spotify track ID') with 100% coverage, so the baseline is 3. The description does not add any input semantics beyond the schema; it focuses on output features.

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 resource (a track's audio features) and lists the specific features (tempo, key, mode, etc.), making the purpose unambiguous. It distinguishes from siblings like get_track implicitly through the unique feature list, though it doesn't explicitly name alternatives.

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

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

Usage is implied by the list of audio features: an agent would use this when needing tempo, key, danceability, etc. However, there is no explicit guidance on when to use this tool versus alternatives, nor any mention of when not to use 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?

Annotations already declare this as safe (readOnlyHint=true, destructiveHint=false, idempotentHint=true). The description adds a summary of returned fields but no side-effect or authentication details. No contradiction with annotations.

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

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

Two short sentences front-load the core action ('Single track by Spotify ID') and immediately list the output. No filler or redundant wording; every word serves a purpose.

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

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

The tool is simple, with fully documented parameters and an output schema present. The description adequately supports selection and invocation. It could mention the optional market parameter's effect on availability, but the schema already covers that.

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 track_id and market both explicitly documented. The description does not add extra meaning beyond what the schema provides, 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 uses a specific verb ('Get') and clear resource ('track'), stating it returns a single track by Spotify ID. It lists the key returned fields (artists, album, popularity, preview URL, duration), which distinguishes it clearly from sibling tools like get_album or get_artist.

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: use this tool when you have a Spotify track ID and need detailed track information. It does not explicitly compare to alternatives like get_audio_features, but the context is unambiguous and there are no exclusions stated.

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

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

The description adds behavioral context beyond the annotations by stating that it returns specific fields ('id, type, params, created_at, last_fired_at, fire_count') and is scoped to the caller's subscriptions. This is consistent with the readOnlyHint and idempotentHint 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 concise: three short sentences with no filler. It front-loads the purpose, then lists return fields and usage guidance. Every sentence contributes value.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers the return shape and usage purpose. Annotations cover safety, and the schema addresses parameters, making the description sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with the include_inactive parameter already having a clear description. The main description adds little new about the parameter, merely implying 'active' by default, which aligns with the schema's 'default false' note. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'List the caller's active subscriptions.' This uses a specific verb ('List') and resource ('subscriptions'), and distinguishes it from sibling tools by noting it is used for reviewing before adding or canceling subscriptions, which aligns with subscribe/unsubscribe 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 provides explicit use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This clearly indicates when to use the tool but does not name alternative tools (e.g., subscribe/unsubscribe) directly, 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 critical behavioral details beyond the all-false annotations: the claim_token return flow, rate limiting ('5 per identifier per day'), zero quota impact, and daily team review. It also clarifies non-destructive nature implicitly (feedback only), and no contradiction with annotations exists.

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

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

The description is front-loaded with purpose, then organized by use-case triggers, exclusions, token mechanics, and constraints. Every sentence adds value—no filler. Although longer than the two-sentence TDQS example, its length is justified by the tool's behavioral complexity and multi-part usage contract.

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 and four params (one nested), the description covers all crucial context: how to file, what to include, when to use alternatives, token-based follow-up, rate limits, and team SLA. Nothing important is left ambiguous.

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 already documents all four parameters, so baseline is 3. The description adds a concrete usage example for claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and specifies 'with no other arguments,' enriching the schema's meaning beyond basic 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 clear verb-resource statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly enumerates feedback types (bug, feature/data_gap, praise) and distinguishes this tool from siblings by limiting scope to Pipeworx-served tools, making its 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?

It provides explicit when-to-use triggers ('Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... when something worked surprisingly well') and a clear exclusion: 'ONLY for tools served by this Pipeworx connection... file it with that server instead.' This is model-level guidance with alternatives articulated.

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

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

Annotations already declare read-only/idempotent/non-destructive; the description adds useful context beyond that: it notes the data is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. This gives the agent a clear picture of freshness and privacy 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 compact and structured: what it returns, when to use it, and data caveats. Each of the three sentences earns its place and front-loads the core purpose.

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

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

For a simple read-only tool with no output schema, the description explains the return contents (top tools, top packs, total call volume), the data shape ((pack, tool, count)), and freshness/caching behavior. The only minor gap is not detailing exact response formatting, but this is not necessary for selection/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?

The single window parameter is already fully documented in the schema with enum values and semantic guidance ('Shorter windows surface what's hot right now'). The description repeats the window options but adds no additional parameter-specific detail, so the schema handles the load; baseline 3 is appropriate.

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

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

The description opens with the interrogative framing 'What other AI agents are calling on Pipeworx right now' and concretely states it returns top tools, top packs, and total call volume over a recent window. This clearly identifies the resource and differentiates it from siblings like discover_tools or ask_pipeworx.

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

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

The description includes an explicit 'Useful for' list with three scenarios, such as confirming a canonical tool before asking a question, which gives clear context for when to use it. It does not name alternative tools directly, so it stops short of full when-not-to-use guidance.

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

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

Beyond the readOnly/idempotent annotations, the description discloses specific behaviors: the top ~200 markets scope, the >3pp deviation threshold, placeholder filtering with >20% threshold, the Jaccard similarity anchor (≥0.30), and the FILL CHECK logic that warns against trading when realizable_edge_pp ≤ 0. No contradictions with annotations.

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

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

Though lengthy, the description is exceptionally well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and a clear front-loaded purpose. Every sentence adds meaningful information about modes, thresholds, or response handling, with 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 complex tool with no output schema, the description provides comprehensive coverage: it explains all three invocation modes, response structure (opportunities[] with gap_pp, suggested_trade, etc.), edge-case handling (placeholder filtering, low similarity), and integration with fill check and other tools. The context signals (2 params, 100% schema coverage) are fully leveraged.

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

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

While the schema already describes the parameters, the description adds rich semantics: accepted input formats (event slugs, full Polymarket URLs, seed questions), examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), and the behavioral implications of each mode. This goes far beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from sibling tools like polymarket_edges and polymarket_edge_tracker by specifying the unique methodology (monotonicity + partition-sum) and by referencing polymarket_fill_risk for sizing, showing clear differentiation.

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

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

Explicit guidance is provided for when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also explains when not to trade via the FILL CHECK section and directs to polymarket_fill_risk for custom sizing, offering clear alternatives and context.

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

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

Annotations already establish read-only/idempotent/non-destructive, so the bar for additional behavioral context is high. The description surpasses it by disclosing caching ('Cached 1h at the KV level keyed on all knobs'), slippage-adjusted edge ('after slippage'), Kelly caps ('capped at 0.25'), placeholder-slug filtering, per-sport bias corrections, and diagnostic fields to explain empty segments. 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 information-dense and structured into clear sections, but it is quite long and includes model internals (e.g., 'lognormal barrier from 90d FRED log-returns', 'GDELT 7d/21d article-volume ratio', per-sport alpha values) that are not essential for tool selection or invocation. The first sentence is a strong front-load, but overall it could be trimmed significantly without losing core guidance.

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

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

With no output schema, the description carries full responsibility for explaining return values. It thoroughly covers the response structure ('by_segment{model_driven,structural_arbitrage,concentrated_longshot}', 'fed_candidates/fed_note', '_diagnostics'), edge fields, why segments may be empty, and parameter behavior. It also explains edge cases like the 24h-move warning and placeholder filters. This is exceptionally 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%, so the baseline is 3. The description adds value beyond schema by explaining parameter logic and interplay, e.g., 'Partition arbs always return kelly_fraction_half=0 at the parent level by design... so min_kelly never filters them — this knob applies to the per-leg Kelly inside top_legs instead.' It also groups parameters as 'TRADEABLE-EDGE KNOBS' and explains their rationale, which goes beyond the schema's 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+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes from sibling tools by describing the unique model-family segmentation (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and the 'what should I bet on today' purpose.

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

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

Explicitly states the intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also provides when-not guidance on Fed bets ('excluded from ranking — 1m-T vs EFFR signal is unreliable at meeting-month horizons'). However, it does not name alternative sibling tools or provide explicit 'use X instead' instructions, 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 important behavioral traits: snapshots are written on cache-miss so gaps mean no scan, history is bounded by a 60-day TTL, and decay is computed from daily closes not intraday. This adds substantial transparency about data availability and limitations.

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

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

The description is dense but well-structured with clear sections (RESPONSE, LIMITS) and front-loaded purpose. Every sentence contributes, and the capitalized section heads make it scannable despite its length.

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

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

With no output schema, the description fully explains the response format: tracked[], expired[], and snapshot_dates[], including specific fields like first_seen, trend, decay_pp_per_day, and lifespan_days. It also addresses limitations and data gaps, making it complete for agent use.

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

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

Schema coverage is 100%, and the description adds useful semantics: days default/clamp and window family (24hr | 1wk | 1mo). While the schema already documents both parameters, the description clarifies the window as a snapshot family and reinforces defaults, adding marginal value beyond schema.

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

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

The description clearly identifies the tool as an edge persistence/decay telemetry tool built from polymarket_edges snapshots, answering 'how long has this edge existed and is it shrinking?'. It uses specific verbs and resource framing, and it distinguishes from sibling tools like polymarket_edges by focusing on historical persistence rather than current edge values.

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

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

The description provides clear context on when to use it: for assessing edge persistence and decay, especially distinguishing fresh vs. old edges. It implies an alternative (polymarket_edges for current edges) but does not explicitly state when-not-to-use this tool or name direct alternatives.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description goes well beyond this by disclosing mode-specific behavior (single-market vs basket), how size_usd is interpreted differently per mode (max spend vs target proceeds vs settlement notional), the internal 'walks the ladder' logic, and the warning about partial fills converting arbs into directional positions. This is rich behavioral context that annotations do not provide.

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

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

The description is long (around 300 words) but every sentence carries necessary information. It is well-structured: purpose, requirements, single-market mode details, basket mode details, and a concluding usage recommendation. It is front-loaded with the core purpose and mandatory inputs. Slightly verbose in listing all return fields, but that detail is useful given there is no output schema. Overall, it earns a 4—not a 5 because it could be tightened without losing value, but it is far from 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 the tool's complexity (two modes, four params, no output schema), the description is remarkably complete. It lists the key return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, verdict, thin_legs[], forced_directional_risk, etc.), explains the risk scenario (partial fills leading to unhedged positions), and provides usage thresholds. It leaves little ambiguity about what the tool does, what inputs it accepts, and what outputs to expect.

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 significant semantic value: it explains that `market` and `event` are mutually exclusive modes, clarifies the default side behavior in basket mode ('auto — sell if partition sum > 1, buy if < 1'), and gives a precise definition of `size_usd` for each mode ('max spend on buys, target proceeds on sells' vs 'settlement notional — shares per leg, each paying $1'). This goes far beyond the schema's one-line 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 opens with a specific verb+resource phrase: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly names the tool's function and distinguishes it from siblings by explicitly referencing `polymarket_arbitrage` and `polymarket_edges` as the tools it supports, and explaining it checks whether theoretical edges are actually capturable given order-book depth.

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

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

The description gives explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial basket fills convert arb into unhedged directional risk), effectively covering when-not-to-use by implying small trades below the threshold don't require it. It names the alternative tools it complements.

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 substantial behavioral disclosure beyond that: gross-vs-net spread caveat due to Kalshi fees, compatibility_codes semantics, non_equivalent_bet_shapes, skipped_unclassified handling, and the pairing_unverified limitation. This goes far beyond what annotations provide.

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

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

The description is long but densely organized with clear labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes). It front-loads the core purpose and then layers details. Some repetition exists around 'same disclosures apply to both modes' and the temporal alignment caveats, but the complexity justifies the length.

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

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

With no output schema, the description carries the full burden of explaining return values and safety behavior. It covers top_spreads_pp, comparison flags, temporal_alignment, skipped_unclassified, low_confidence_pairs, fees_note, skipped_cross_type/subtype counters, and the pre-mapped-not-tradeable caveat. Nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining that topic and explicit parameters are two alternative modes that both run the identical token-overlap matcher, and that explicit parameters override the mapped side. This clarifies the relationship between parameters rather than just restating 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 opening sentence states a precise verb-noun pair: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It then enumerates two concrete modes and what each returns, making the tool's purpose unmistakable and clearly distinct from siblings like polymarket_arbitrage or polymarket_edges.

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

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

The description gives clear when-to-use guidance for the two modes (topic shortcuts vs explicit ticker/slug) and warns that pre-mapped topics are often not tradeable. It does not name sibling alternatives explicitly, so 'use X instead' guidance is absent, but the context for using this tool is well specified.

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

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

Annotations already declare read-only and idempotent behavior. The description adds valuable context about scoping to an identifier (anonymous IP, BYO key hash, or account ID), which explains data isolation. This goes beyond the annotations and clarifies an important behavioral trait.

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

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

The description is concise and well-structured: it opens with the core action, then provides usage context, then scoping and paired tools. Every sentence adds value, with no redundancy or fluff.

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

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

For a simple read-only lookup tool with one optional parameter and no output schema, the description is complete. It covers purpose, usage scenarios, scoping, and related tools, leaving no critical gaps for an agent to misuse 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 description coverage is 100%, and the parameter's meaning is fully described in the schema ('Memory key to retrieve (omit to list all keys)'). The description reinforces this but does not add meaningful new semantics beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: retrieve a previously saved value or list all keys when the key argument is omitted. It uses a specific verb (retrieve/list) and resource (saved memory), and distinguishes itself from siblings by explicitly referencing remember and forget.

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

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

Explicitly states when to use the tool ('Use to look up context the agent stored earlier') and provides concrete examples of use cases. It also names the complementary tools (remember, forget) and clarifies the scope, which helps the agent decide when this tool is appropriate.

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

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

Annotation contradiction: annotations declare readOnlyHint: true, but the description says 'Set mark_read:true to flag returned events read so the next call only shows newer ones', which is a state-changing side effect. This directly contradicts the read-only hint, so the description does not align with structured metadata.

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 long, front-loaded with the core verb and resource, and every sentence adds information: return contents, filtering, mark_read semantics, polling suitability, and an alternative endpoint. No waste 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?

Despite lacking an output schema, the description specifies exactly what each alert carries (source, citation_uri, raw event payload). It covers filtering, read-state management, polling, and alternative access. With rich annotations and full schema coverage, this is complete for a read/poll 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 description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by providing a concrete type example ('sec_8k'), clarifying that type and since can be combined ('and/or since'), and explaining the behavioral consequence of mark_read. This meaningful addition justifies a 4.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Pull fired events from your subscription feed.' It further distinguishes from siblings by explaining it returns alerts written by the evaluator, which is unique among tools like list_subscriptions or recent_changes.

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

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

The description provides practical usage guidance: 'Filter by type (e.g. "sec_8k") and/or since (ISO timestamp)', notes that 'Polls work fine', and offers an alternative access path via HTTP endpoint for scripts/dashboards. It lacks explicit when-not-to-use vs sibling 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses important runtime behaviors: GDELT-to-GNews fallback on rate limits or 5xx, USPTO soft-failing due to PatentsView API sunset, supported `since` formats, and the exact return shape (changes[] grouped by source, total_changes, pipeworx:// citation URIs). This is rich, non-obvious context that annotations alone could not convey.

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

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

The description is long but every sentence and clause carries operational value: user intents, source list, fallback logic, soft-fail caveat, parameter format, return structure, and pointer to alternative. It is front-loaded with the core purpose and uses punctuation effectively to pack information 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?

Given the tool's multi-source complexity and lack of an output schema, the description is remarkably complete. It explains not only what the tool does, but how it fails (USPTO soft-fail), how it falls back, what the response contains, and when to choose a sibling tool. No critical aspect of expected behavior or input constraints is undocumented.

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% parameter descriptions, including examples for `since` and `value` and the enum restriction for `type`. The description repeats most of this information (e.g., ISO/relative shorthand, ticker or CIK) and adds only minor clarifications like 'Use "30d" or "1m" for typical monitoring,' which is also in the schema. No significant new meaning is added beyond the structured schema.

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

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

The description opens with concrete user intents ('What's new with X', 'latest on Y') and explicitly identifies the tool as a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It clearly distinguishes itself from entity_profile by stating when to use that alternative, and lists the specific data sources (SEC EDGAR, GDELT/GNews, USPTO) that define its scope.

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

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

The description gives explicit usage guidance: use for time-bound change queries across multiple sources, and use entity_profile instead for the static profile regardless of window. It also explains the fallback behavior between GDELT and GNews, which helps the agent decide when this tool is appropriate for news-related queries.

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 idempotency and non-destructive hints. The description adds that data is stored 'as a key-value pair scoped by your identifier' and details persistence (24 hours for anonymous, persistent for authenticated), which is genuinely useful context beyond annotations.

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

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

The description is four sentences, each earning its keep: purpose, when to use, storage/scoping behaviors, and related tools. It's front-loaded with the primary action and avoids fluff.

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

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

For a simple two-parameter tool with no output schema, the description covers what, when, and persistence semantics. It doesn't discuss return values or overwrite behavior, but given the simplicity and annotations, it's sufficiently complete for an agent.

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

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

Schema description coverage is 100% for both key and value parameters, so the baseline is 3. The description reinforces the key-value model and provides example keys, but does not add substantially new parameter-level meaning 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 immediately states the core action: 'Save data the agent will need to reuse later.' It provides concrete examples of what to store (ticker, address, preference) and explicitly pairs with recall/forget, clearly distinguishing 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?

It gives a clear trigger: 'Use when you discover something worth carrying forward.' It also explains the persistence difference between authenticated and anonymous sessions, and mentions recall/forget as complementary tools. It lacks an explicit 'do not use for X,' but the guidance is strong.

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

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

Beyond the annotations, the description discloses rich behavioral context: it cascades through several lookup endpoints, degrades gracefully when GLEIF/OpenFIGI are unavailable, returns figi_candidates on ambiguity, explicitly lists unresolved identifiers, and labels every identifier with its source. No contradiction exists between the description and the annotations.

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

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

The description is dense and front-loaded with query examples and the primary directive 'Use FIRST'. It is longer than average, but the length is justified by the tool's complexity, covering two entity types, multiple identifier sources, edge cases, and failure behavior. Minor redundancy in the example list 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?

The description is comprehensive for a tool with no output schema: it covers both entity types, all accepted input forms, ambiguous-match behavior, unresolved-identifier handling, source attribution, and graceful degradation. An agent has enough information to know when and how to invoke it correctly, and what to expect back.

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 crucial semantic guidance beyond the schema: it explains accepted input formats (ticker, CIK, ISIN, name), warns against passing full noun phrases such as 'NEW YORK ST DORM AUTH revenue bonds', and gives concrete examples for drug names. This materially improves correct invocation.

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

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

The description states a specific action ('resolve a user-spoken NAME to the canonical/official identifiers other tools require as input') and explicitly lists the supported entity types and identifier systems (CIK, LEI, FIGI, RxCUI). It is clearly differentiated from sibling tools by focusing on identifier resolution rather than profiles, comparisons, or research.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID,' and includes concrete query-phrase examples. It does not name alternative sibling tools or state when NOT to use it, but the context and identifier-focused purpose make usage conditions clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it probes each entity, treats the first entity as the subject for narrative, and returns a ranked list with score, confidence, and signal density. This is extra context beyond annotations, though it doesn't cover rate limits or error behavior.

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

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

The description is four sentences, each adding value: purpose, mechanism, use case, and output. It is front-loaded, avoids redundancy with schema, and every sentence earns its place.

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

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

Without an output schema, the description's mention of a ranked list with score, confidence, and signal density is valuable. It also explains orchestration over ai_visibility_check and subject/competitor ordering. With rich annotations and full schema coverage, this is complete enough for an agent.

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

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

Schema description coverage is 100%, with detailed parameter descriptions. The tool description repeats the entity ordering ('your brand + N competitors') already present in the schema, adding no new meaning for parameters. Hence it stays 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 states a specific action (compare AI visibility across entities), the resource (entities), and the method (probe with ai_visibility_check and rank). It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by emphasizing AI visibility and ranking.

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

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

Provides a clear use case: competitive AI-marketing audits, with a concrete example query. However, it doesn't explicitly state when not to use it or name alternatives such as ai_visibility_check for single-entity checks, so it's a 4 rather than 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 rich behavioral details beyond annotations: composite fan-out across multiple APIs, partial failure degradation, the 5-30s first-measurement delay from bundlephobia, and the sources_failed field that reports timeouts. This goes well beyond the readOnlyHint/idempotentHint annotations and provides actionable expectations for the agent.

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 information-dense and front-loaded with the core purpose in the first clause. Every sentence adds value, but the long list of output fields and the lengthy parenthetical about timing make it slightly more verbose than ideal. Still well-structured and efficient for the complexity.

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

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

Given the tool's complexity (composite multi-source check, no output schema), the description is remarkably complete: it lists the output summary fields, mentions per-advisory detail, links, and alternative versions, and explains failure behavior under partial outages. It gives enough context for an agent to know what to expect and how to handle anomalies.

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 adds minimal parameter-specific meaning beyond the schema: it mentions scoped packages and default version behavior, but these are already in the schema. The parameter semantics are fully handled by the schema, so no extra credit beyond baseline.

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

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

The description opens with a specific verb-resource-scope statement: "Composite 'should I add this npm package to my project' check in ONE call" and immediately lists the data sources (deps.dev, bundlephobia). It clearly distinguishes from siblings like scan_competitor_ai_presence by focusing on npm package evaluation with a distinct 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: "Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'." It also states an exclusion and alternative: "NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly."

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds some context (supported types and named sections in results), but does not disclose rate limits, auth requirements, or pagination details. This is adequate but not rich.

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

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

The description is extremely concise, with three short sentences front-loaded with purpose. Every piece of information earns its place, with no redundant or filler content.

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

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

Given the tool's moderate complexity (5 params, output schema present, annotations provided), the description is sufficient. It covers the core behavior and type semantics, while schema and annotations handle the rest. Some usage guidance is missing but not critical for this tool.

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

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

Schema description coverage is 100%, providing baseline 3. The description adds value by enumerating valid type values (album, artist, playlist, track, show, episode, audiobook) which are not fully listed in the schema property, and clarifies the return structure as named sections.

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

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

The description clearly states the tool searches the Spotify catalog, with a specific verb and resource. It mentions the type parameter and return behavior, but does not explicitly contrast with sibling tools like search_within, so it lacks full differentiation.

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

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

The description implies usage as a general catalog search by naming the catalog and supported item types, but provides no explicit guidance on when to use this tool versus alternatives (e.g., search_within) or any exclusion 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the return format (top-N passages with character offsets and similarity scores), the technical approach (BGE-base-en embeddings, cosine over 500-char overlapping windows), and the 200K char cap with truncation flagging. This is rich behavioral context that annotations alone don't 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 earns its place: purpose, input semantics, output value, usage scenario, pairing guidance, and technical constraints. It is well-structured, front-loaded with the core purpose, and 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 there is no output schema, the description fully compensates by stating return values (passages with offsets and similarity scores), the truncation behavior, and the embedding details. For a 3-parameter tool with strong annotations, this is a complete and self-sufficient description.

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

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

The schema already covers all three parameters with descriptions (100% coverage). The description adds meaningful context with concrete examples: text as 'a SEC 10-K body' and query examples like 'supply-chain risk,' plus reinforcement of the 200K char cap. This exceeds the baseline for full schema coverage without being redundant.

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

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

The description starts with 'Semantic search INSIDE a fetched record,' a specific verb+resource+scope that immediately distinguishes it from the sibling 'search' tool and clarifies its niche. It also mentions pairing with 'ask_pipeworx_grounded,' reinforcing its distinct role in a workflow rather than as a generic search.

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 guidance: 'Use when the record is too big to cram into the prompt' and explains how it pairs with ask_pipeworx_grounded ('fetch with the gateway, ground over the relevant passages instead of the whole document'). This is clear when-to-use and alternative/mitigation context.

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

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

Beyond the annotations, the description discloses auth requirements, persistence limitations, delivery channel options, phone verification, SMS caps, webhook HMAC signing, and auto-disable after 10 failing runs. It also notes that the response includes the new subscription ID and one-time webhook secret, providing rich behavioral context.

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

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

The description is longer than average but front-loaded with the purpose and packed with necessary operational details. Every sentence contributes value, though the density could be slightly intimidating. 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?

The tool has moderate complexity (nested objects, multiple types, optional delivery options) and no output schema. The description covers the return value, auth prerequisites, type-specific parameters, delivery mechanics, and failure/limit behavior, 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?

Although the schema already has 100% coverage, the description adds concrete examples for each subscription type (e.g., items:['5.02'] for sec_8k, topic:'fed' for polymarket_edge) and elaborates on delivery constraints (E.164 format, verified phone, HTTPS-only webhooks). This significantly enhances meaning 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 action ('Create a proactive monitoring subscription') and the resource ('live-data event stream'). It is distinct from sibling tools like list_subscriptions and unsubscribe, focusing on creation rather than listing or deletion.

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

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

Provides explicit context: requires a Pipeworx OAuth account, mentions that anonymous and BYO cannot persist subscriptions, and offers an alternative for reading alerts ('pull via recent_alerts or GET registry.pipeworx.io/alerts.json'). This gives clear when-to-use and when-not-to-use signals.

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/destructive=false. The description adds valuable context about the return structure (category-bucketed examples with tool + argument shape) and how topic affects the output. 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 opens with a long list of six paraphrased user questions ('What can I ask?', 'what can you do?', etc.) that are largely redundant. The core explanation is informative but could be more streamlined.

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

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

With no output schema, the description adequately explains the return value (category-bucketed examples with tool + argument shape) and covers invocation variants (no args versus topic). It provides complete context for an onboarding 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%, fully describing the optional `topic` parameter with valid values and omit behavior. The description only repeats examples like 'finance' and 'pharma', adding no new information 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 it is the onboarding entry point that returns category-bucketed example questions with the exact tool + argument shape. It distinguishes itself from siblings by positioning as 'Use this FIRST' and teaching how to call meta-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 says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and gives examples like 'getting started'. It provides clear when-to-use context, though it doesn't explicitly name alternatives for when not to use.

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

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

Adds valuable behavior beyond annotations: ownership enforcement, deactivation instead of deletion, and preservation of historical events via recent_alerts. This complements the idempotent and non-destructive hints without contradicting them.

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

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

Three concise, front-loaded sentences. Every sentence provides relevant information without fluff, making it easy to parse.

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

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

Given the tool's simplicity (one parameter, no output schema), the description fully covers the action, behavioral outcomes, and the relationship to recent_alerts. It could mention the response format, but that isn't critical for a simple mutation.

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

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

Schema coverage is 100% and the description repeats 'id' without adding new meaning beyond the schema's own description. Baseline 3 is appropriate as the schema does the heavy 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 states 'Cancel a subscription by id' with a specific verb and resource, clearly distinguishing it from sibling tools like subscribe. The ownership enforcement clause further clarifies the intended action.

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 (canceling a subscription) and provides context about ownership. It doesn't explicitly mention alternatives or when-not-to-use, but the purpose is clear enough given the sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: it explains the two execution paths (SEC EDGAR vs grounded pipeline), clarifies the meaning of the 'could_not_verify' versus 'unsupported' verdicts, and warns that 'could_not_verify' must not be treated as evidence. This goes far beyond the annotation hints.

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 yet information-dense. Every sentence earns its place: examples, purpose, routing logic, return values, and a critical caller warning. The structure with an 'IMPORTANT' section effectively highlights the 'could_not_verify' caveat, and the overall length is appropriate for the tool's complexity.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It enumerates the verdicts ('confirmed', 'approximately_correct', 'refuted', 'inconclusive', 'unsupported', 'could_not_verify'), mentions the actual value with citation, and describes reasoning. It also covers edge cases like 'could_not_verify' versus 'unsupported', making it complete for a complex claim-verification 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 both 'claim' and 'tolerance_pct' have detailed descriptions in the schema. The tool description adds little beyond the schema — it mentions tolerance_pct in the context of hallucination detection and gives claim examples, but these are already in the schema. The baseline of 3 applies since the schema does the heavy 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 clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides a specific verb ('validate'), the resource ('claim'), and examples of user phrasings. It also distinguishes from siblings by noting it replaces multiple sequential calls (NL parsing → entity resolution → data lookup → comparison) and handles both structured SEC EDGAR and grounded pipelines.

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

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

The description gives explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing logic for different claim types, providing clear context. However, it does not explicitly list when-not-to-use or name alternative tools, so it does not fully satisfy the highest bar.

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