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?

Annotations already declare readOnly/openWorld/idempotent, and the description adds useful context: it routes to specific tools, fills arguments, returns stable citation URIs, and works on every tier with one fast call. It does not discuss potential failures or rate limits, but given the strong annotation coverage, the added context is sufficient.

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

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

The description is long but front-loaded with the key instruction. While it includes specifics like tool/source counts that could be considered extra, most sentences serve a purpose: usage triggers, examples, and sibling differentiation. It could be slightly more structured, but it remains readable and efficient.

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

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

For a single-parameter read-only tool without an output schema, the description is remarkably complete. It covers when to use, what it does, what it returns (structured answer with citations), alternatives, and limitations. No material gaps remain for an agent to invoke it correctly.

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

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

Schema coverage is 100% with descriptions for the 'question' property and all aliases. The description adds value by providing concrete examples and reinforcing that the parameter accepts natural language queries, which goes beyond the schema's basic alias explanation.

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: it routes factual questions to one of 5,529 tools across verified sources and returns structured answers with citation URIs. It distinguishes from siblings like ask_pipeworx_grounded and deep_research by specifying when each is appropriate, and it uses an imperative verb ('PREFER OVER WEB SEARCH') that conveys the tool's role.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', then provides precise alternatives: use ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part queries. It also lists trigger phrases and examples, making the when-to-use guidance extremely actionable.

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

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

Annotations already provide safety profile (readOnly, idempotent, non-destructive). The description adds crucial context: it is experimental with candidate routing changes enabled live, currently identical to stable, and falls back to nothing (full working router). This transparency exceeds the annotation baseline and addresses potential misconceptions.

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-bearing but somewhat lengthy at ~90 words. It is front-loaded with the beta purpose and current status, though the parenthetical date could be trimmed without loss of essential guidance. Still efficient overall.

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 experimental nature and absence of an output schema, the description sufficiently covers what it is, current behavior, usage instructions, and the fact that it is a fully functional router. Referencing the same response shape as ask_pipeworx and naming the stable alternative provides complete context.

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

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

Schema description coverage is 100% covering all six parameters (question plus five aliases). The description mentions 'same arguments' but adds no extra parameter meaning beyond what the schema already documents. Baseline 3 is appropriate when schema carries the burden.

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

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

The description clearly identifies this as a beta variant of ask_pipeworx with the specific role of a universal router using the same 5,529 tools and arguments. It distinguishes from the stable ask_pipeworx by highlighting experimental routing improvements, so the purpose is specific and not a tautology.

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

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

Explicitly states when to use: 'Use it exactly like ask_pipeworx when you want the newest routing' and notes results are compared against the stable router. The current inactive-candidate state and exact matching with ask_pipeworx further clarify usage context.

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

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

Annotations declare readOnly/openWorld/idempotent/non-destructive, and the description adds rich behavioral context: it routes through 5,529 tools, fetches data, extracts only from the tool result, returns verbatim evidence, and provides a structured refusal with specific refusal reasons. It also discloses the cost of an extra LLM call, which is beyond what annotations capture.

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: opens with the core purpose, explains the mechanism, gives the return contract and refusal reasons, then usage guidance. Every sentence carries distinct information; no fluff or tautology.

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

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

For a read-only query tool with no output schema, the description is fully complete: it covers return shape, evidence format, refusal reasons, cost, and alternatives. The output schema is absent, but the description compensates by specifying the exact response structure.

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 clarifies that all six parameters are aliases for a single natural-language question, reinforcing the schema. It also explains the input is a natural-language question routed to other tools, which adds semantic context beyond the raw schema. Minor deduction because no additional parameter-specific details are needed given full 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 defines a specific verb+resource: a hallucination-resistant answer mode that returns extracted answers with evidence and explicit refusals. It distinguishes itself from sibling 'ask_pipeworx' by emphasizing grounded extraction and refusal behavior, and it names its unique return contract.

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: high-stakes reads, when answers will be quoted/cited/acted on, and when the agent must not invent facts (financial, legal, medical, public statements). It also provides a clear alternative: prefer ask_pipeworx for casual lookups, and notes the extra LLM call cost.

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?

Despite annotations already declaring readOnly/openWorld/idempotent, the description adds substantial behavioral context: account tiers, gap handling ('gaps[] ... never invented'), contradiction scanning, semantic excerpting, latency expectations, and the fetchability guarantee of citations. No contradiction with annotations.

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

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

The description is long but every sentence earns its place. It is front-loaded with the critical account/paid requirement and alternatives, then organizes research behavior, output details, and latency in a logical flow. Despite density, it remains readable and scannable.

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

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

Given the tool's complexity, no output schema, and rich annotations, the description covers all necessary aspects: use cases, exclusions, output structure, limitations, latency, citation semantics, and alternate tools. It is fully self-sufficient for an agent to decide when and how to invoke 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?

Even though the schema covers 100% of parameters, the description enriches both `question` and `depth`: it explains that broad/multi-part questions are expected, details what each depth tier does (quick/standard/thorough hop behavior, gap recovery, contradiction scan), and clarifies defaults. This goes well beyond the schema enum descriptions.

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

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

The description clearly states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources ... in ONE call'. It explicitly distinguishes itself from open-web search and from the sibling ask_pipeworx, making its unique scope 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?

Provides explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. Also notes the account requirement and falls back to ask_pipeworx when signed out.

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?

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds rich behavioral context: parallel fan-out across multiple data sources, specific return structure with pipeworx URIs, patent sunset soft-fail mechanism, and GDELT→GNews fallback. This goes well beyond the annotations.

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

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

The description is densely packed but well-structured: starts with user-facing examples, then the core purpose, followed by technical details. Every sentence provides value without redundancy, and it is appropriately sized for the tool's complexity.

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

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

Despite having no output schema, the description fully enumerates all returned fields (cik, recent_filings, fundamentals, patents, news, LEI), data source fallbacks, sorting, and known limitations (patent sunset, name unsupported). This is complete for an agent to invoke and interpret results.

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

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

Schema coverage is 100% with both parameters described in detail, including examples and the name restriction. The description repeats this information but does not add new semantic meaning beyond the schema. Thus 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 explicitly states it provides a 'full cross-source profile of a US public company in ONE parallel call' and enumerates the sources and return fields. It distinguishes itself from sibling tools by emphasizing it should be preferred over chaining single-pack lookups and referencing resolve_entity for names.

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

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

Clear usage guidance is provided: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and explicit instruction to use resolve_entity first when only a name is available. This gives the AI agent concrete decision criteria.

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

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

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 cover readOnlyHint and idempotentHint, but the description goes far beyond by disclosing the response structure (leg-by-leg prices, spread[].top_spreads_pp), the safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype), and the edge cases where no arbitrage exists. It also explicitly states that the tool indicates when bet shapes are non-equivalent, which is critical behavioral transparency.

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

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

The description is long but well-structured with clear labels like 'TWO MODES' and 'SAFETY FIELDS'. Every sentence provides necessary information about the tool's behavior, but it is denser than strictly necessary. The structure makes it accessible, though a more concise version could have been written without losing key details.

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 listing the key response fields and their meanings, including the spread calculation, compatibility_warning conditions, temporal alignment, and skipped counters. It also covers the main limitation ('pre-mapped ≠ tradeable'), making it complete for a cross-venue spread tool with this complexity.

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

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

All three parameters are documented in the schema, so the baseline is 3. The description adds meaning by explaining the two modes: 'topic' auto-fetches a matching event on each venue, and explicit ticker/slug override the topic mapping. This goes beyond the schema examples and clarifies how the parameters interact, justifying a score above baseline.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which is a specific verb-and-resource statement that clearly distinguishes it from sibling Polymarket-only tools like polymarket_edges and polymarket_arbitrage. It then details the two modes, further specifying the tool's exact functionality.

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

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

It provides explicit guidance on when to use each mode (topic shortcuts vs explicit ticker/slug) and explains the compatibility_warning conditions that indicate when a spread is not meaningful. The warning that 'most pre-mapped topics return compatibility_warning today' is a strong use-case caveat. However, it does not name sibling tools or explicitly state when to prefer an alternative tool.

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

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

Annotations already 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 (readOnlyHint, idempotentHint), the description adds unique behavioral context: 'LEI/FIGI enrichment degrades gracefully', 'an identifier that could NOT be resolved is stated explicitly under unresolved rather than omitted', and 'Each call cascades through several lookup endpoints internally.' These traits are not present in annotations.

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

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

The description is well-structured, front-loading example queries and the core use case before diving into type-specific details. It is somewhat verbose, with minor redundancy between the opening sentence and the 'Use FIRST' instruction, but the length is justified by the complexity of the tool's two entity types and their behaviors.

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

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

Since there is no output schema, the description compensates by explicitly listing return values for both company and drug types, including the `unresolved` field. It also covers failure behavior (graceful degradation), source labeling, and efficiency benefits ('replaces 2-3 manual lookups'), making it fully adequate 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% with descriptions for both parameters, but the description adds specific formats (10-digit CIK, 'ozempic', 'metformin'), source attribution (SEC EDGAR, GLEIF, OpenFIGI), and expected return fields (RxCUI + ingredient + brand). This goes beyond the schema's basic type/value 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 and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes from siblings like entity_profile by instructing 'Use FIRST whenever you have a name but need an ID.' Supported types are explicitly listed with input/output details.

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

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

The description explicitly states when to use ('Use FIRST whenever you have a name but need an ID') and implies when not to use (when you already have an ID, use other tools). It names alternatives indirectly ('other tools require as input') and clarifies the supported entity types and their accepted inputs.

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.