musicurainz

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses important behavioral details: the default model, the optional Anthropic key with direct billing ('BYO key — you pay Anthropic directly'), and the exact return shape ('per-model {score, confidence, signals, raw_response} + a combined view'). This adds meaningful context beyond what annotations provide, with no contradictions.

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: three sentences cover the core action, key model options with cost implications, and return format plus use cases. Every sentence adds distinct value without unnecessary fluff, and the most critical information is front-loaded.

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

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

Given the tool's moderate complexity (4 params, no output schema), the description is complete: it explains the output structure despite the absence of an output schema, covers the main parameters' intent, and provides context for when to use it. The 100% schema coverage ensures parameter details are available, and the description fills the remaining gaps about cost and default behavior.

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 all parameters (100% coverage), the description adds valuable semantics: it clarifies that '_apiKey' is only needed if 'anthropic' is in models and that Workers AI is free by default. This enriches the meaning of the 'models' parameter and the optional key, going 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 function with a specific verb and resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It also specifies the output format and use cases, effectively distinguishing it from sibling tools like scan_competitor_ai_presence by focusing on general entity visibility rather than competitor-specific 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 concrete use contexts: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also gives guidance on model selection ('Default model is Workers AI Llama-3.3-70b (free); pass _apiKey to also probe Anthropic'), but it does not explicitly state when not to use this tool or mention alternative 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 read-only, idempotent, open-world, and non-destructive behavior. The description adds meaningful context beyond annotations: routing logic, argument filling, stable pipeworx:// citation URIs, tier availability, and 'one fast call'. No contradictions found, though latency or failure modes are not discussed.

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

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

The description is long but front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and structured into clear sections: scope, trigger phrases, examples, and escalation paths. Minor redundancy exists between 'Use whenever the user asks' and 'START HERE', but each section contributes practical 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 broad query-routing tool with no output schema, the description is complete: it specifies the domain, gives concrete examples, names alternatives, explains the routing behavior, and states the return format (structured answer with citation URIs). An agent has enough context to decide when to invoke and what 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 description coverage is 100%, with all parameters documented as aliases for 'question'. The description reinforces that input is a natural-language question but does not add new parameter semantics beyond the schema. Baseline of 3 is appropriate since the schema handles the parameter detail fully.

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 ask_pipeworx as a natural-language question router that answers factual queries across 5,529 tools and 1,455 sources, returning structured answers with citation URIs. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as step-up alternatives, and contrasts with web 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?

Usage guidance is explicit and actionable: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and trigger phrases like 'what is', 'look up', 'find', 'get the latest'. It also names alternatives and states when to use them, covering both escalation paths and breaking-news handling.

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

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

The description adds valuable context beyond annotations: it is experimental, may have candidate routing improvements live, and currently matches ask_pipeworx exactly. It also reassures that it is a full working router, not a fallback stub. This goes beyond the read-only/idempotent 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 a single, dense paragraph that front-loads the key fact (beta version) and explains the current match with ask_pipeworx. It is slightly repetitive (e.g., 'identical' and 'same') but every sentence contributes useful information without 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 universal router with no output schema, this description covers what it does, how it differs from the stable version, its current state (no active candidate), and usage expectation. It relies on the sibling name for response shape details, which is acceptable given the sibling tool is present in context.

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

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

Schema coverage is 100% with clear descriptions for the 'question' parameter and its aliases. The description adds no additional parameter detail beyond saying 'same arguments' as ask_pipeworx, which is helpful only if the agent knows that tool. Baseline 3 is appropriate 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 identifies this as a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable sibling by noting candidate routing improvements and experimental edge status.

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 'Use it exactly like ask_pipeworx when you want the newest routing', providing clear when-to-use guidance. It implicitly suggests the stable router for non-experimental use, and mentions comparisons against the stable router for merging decisions, but does not explicitly list alternatives or say 'don't use for production'.

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 rich behavioral context beyond the annotations: it extols extraction that uses 'ONLY what the tool result contains,' discloses refusal reasons with specific codes (not_in_source, no_tool_match, etc.), and notes the extra LLM call cost. This goes above the readOnly/idempotent hints and gives the agent a clear picture of the tool's 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 a long paragraph, but it is structured and front-loaded with the core purpose. Every sentence adds value: mechanism, return shape, refusal reasons, use cases, and trade-off. It is slightly dense but not wasteful, earning a 4 rather than a 3 for some redundancy in the refusal explanation.

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 details the response shape and possible refusal reasons. It also covers use cases, cost implications, and relationships to siblings. Combined with the annotations, this gives a complete operational picture 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% — all six parameters are aliases for the question and are documented in the schema. The description does not add new parameter semantics beyond mentioning that the tool 'fills arguments' during routing, which is internal behavior rather than parameter usage. Baseline 3 is appropriate since the schema carries the load.

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

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

The description opens with a specific purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes itself from sibling 'ask_pipeworx' by noting identical routing but grounded extraction using ONLY tool result content, and explicitly names the cost difference. This is a specific verb+resource with sibling differentiation.

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

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

Explicit guidance is given: 'Use whenever an answer will be quoted, cited, or acted on...' and 'prefer ask_pipeworx for casual lookups.' This tells the agent when to use this tool versus the named alternative, fulfilling the when-to-use and when-not-to-use requirement.

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

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

The description goes far beyond the annotations, detailing the resolver contract, suppression of analysis fields on low-confidence matches, blocking routes for closed markets, spread thresholds, cancellation-rule parsing, and fallback behavior for news sources. This discloses edge cases and safety behaviors that annotations cannot express.

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

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

The description is long but well-organized into capitalized sections, front-loading the purpose and usage before details. Each sentence adds specific behavioral information; however, it could be tightened in places (e.g., detailed fan-out examples and resolution-rule risk paragraphs).

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

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

With no output schema, the description fully compensates by enumerating response shapes (result.market, analysis, evidence), resolver match fields, parent_event structure, news fallback flags, and safety/error states. It covers all meaningful edge cases for the tool's complexity.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds value by showing how the 'market' parameter is interpreted via classifiers and fan-out examples (e.g., BTC bet → coingecko+fred+gdelt), and clarifies the meaning of resolution confidence. However, it doesn't discuss 'depth' or 'include_raw' in the text, so it doesn't elevate beyond the schema's parameter 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 opening sentence clearly states a specific verb ('Research') and resource ('a Polymarket bet' via 'Pipeworx data'), and the description distinguishes this from sibling tools by emphasizing the one-call fan-out to category-specific data packs. It also explains input flexibility (slug, URL, question text), which is more specific than generic tool 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?

The description explicitly says 'Use for' with three concrete query patterns: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. This gives clear context, though it doesn't explicitly exclude other sibling tools or name alternative tools for different use cases, so it falls short of a 5.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable context beyond that: data sources (SEC EDGAR/XBRL for company, FAERS/FDA/trials for drug), handling of off-calendar fiscal years (AAPL Sep, NVDA Jan), sorting by primary metric, and output format (paired data + citation URIs). No contradictions with annotations.

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

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

The description is front-loaded with trigger phrases and immediately states the core purpose. Every sentence adds information: scope, data sources, fiscal year handling, sorting, output, and efficiency gains. Despite being detailed, it remains tight and readable with no filler. It earns its length.

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

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

Given the tool's complexity (different entity types, data sources, comparison logic) and no output schema, the description covers all essential aspects: when to use it, what data is pulled per type, edge cases (off-calendar fiscal years), result organization (sorted by primary metric), and output format (paired data + citation URIs). It is complete for an agent to select and invoke the tool correctly.

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

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

Although the schema has 100% coverage, the description enriches parameter meaning substantially. For the 'type' parameter, it explains what data each enum value retrieves (latest 10-K financials vs. adverse events/approval/trials). For 'values', it clarifies the expected format for companies (tickers/CIKs) and drugs (names), with examples. This goes well 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 function: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It specifies the verb 'compare', the resource 'entities' (companies/drugs), and the scope (2–5 items). It also distinguishes itself from sibling tools by referencing 'sequential single-pack lookups' and stating it replaces 8–15 sequential lookups. The trigger phrases further clarify intent.

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 this tool: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides clear trigger phrases ('compare X and Y', 'X vs Y', 'rank these companies') and implies when not to use it (single entity lookups, which are handled by sibling tools like entity_profile). This gives strong usage direction.

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

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

Annotations already mark readOnly/idempotent/openWorld, and the description goes beyond these: notes account and paid-tier requirements, explains that findings are always sourced with confidence scores and gaps[], never invented, includes timing estimates, and that citations are only included when fetchable. This exceeds the annotation baseline significantly.

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 long, the description is densely structured: each sentence covers a distinct aspect (auth, alternatives, decomposition, output format, depth behaviors, timing). No filler or repetition; front-loads the tool's primary purpose and account gating.

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, multi-step research tool with no output schema, the description covers the return packet (verbatim evidence + confidence + source + fetched_at + citation + gaps[]), contradictions, excerpting behavior, hop field, and performance expectations. This fully compensates for the missing output schema and leaves no major ambiguity.

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

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

Schema descriptions for question and depth are complete (100% coverage), explaining broad/multi-part questions and each depth level's facet counts and recovery passes. The tool description adds behavioral context (paid tier, timing) but little new parameter-level semantics; the schema already carries the meaning. Baseline 3 applies.

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

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

Description opens with a specific verb-object pair: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explicitly contrasts with open-web search. It names the tool's core value (parallel decomposition across 5,529 tools) and distinguishes from siblings by mentioning ask_pipeworx for single lookups and breaking news.

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 best-fit use cases: 'Best for broad/multi-part questions over structured data' and gives examples. Provides clear alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and account fallback if unsigned in.

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 that results include 'names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly, no second schema lookup needed,' which enriches the expected behavior. No contradictions found.

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 compact three sentences that front-load the core purpose, then list domains, then explain the return value. It's slightly dense due to the long domain list but remains efficient and readable.

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

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

Given the simple schema and read-only annotations, the description covers what the tool does, when to use it, and what it returns. It lacks an explicit statement about empty results or edge cases, but that's not critical for a discovery 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%, with all parameters documented, including aliases and limit. The description adds minimal extra meaning beyond the schema, mostly reinforcing that the query is a natural language description. 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 'Find tools by describing the data or task,' clearly stating the tool's verb and resource. It distinguishes itself from siblings by being a meta-tool for discovering other tools, reinforced by 'Call this FIRST when you have many tools available.'

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 when you need to browse, search, look up, or discover what tools exist...' and adds a strategic cue to call this first when many tools are available. This clearly positions the tool against alternatives, even without naming specific 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, and idempotentHint. The description adds valuable context beyond annotations: it states the tool fans out across multiple sources, returns specific fields, and discloses that the USPTO PatentsView API sunset in May 2025 causes a soft-fail. This is useful behavioral transparency without contradicting annotations.

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

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

The description is a single dense run-on sentence with semicolons, but every clause adds relevant information: trigger examples, preference over chained lookups, return fields, API warnings, and input constraints. It is parseable but could benefit from bullet points or sentence breaks to improve readability.

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 and the absence of an output schema, the description thoroughly conveys the return structure (fields, sources, URIs), the parallel fan-out behavior, input validation, and a known external dependency (patents API sunset). It gives an agent enough context to decide when to use the tool and what results 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?

The input schema fully describes both parameters, including examples ('AAPL', '0000320193') and the note about unsupported names. The description repeats these examples and constraints but adds no new information beyond what the schema already provides. With 100% schema coverage, the baseline of 3 applies.

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

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

The description clearly states the tool's purpose as producing a 'full cross-source profile of a US public company in ONE parallel call' and enumerates exactly what it returns (CIK, filings, fundamentals, patents, news, LEI). It distinguishes itself from siblings like resolve_entity by explicitly stating that names are not supported and directing users to use resolve_entity first.

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

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

The description provides explicit usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and gives clear exclusions ('names not supported — use resolve_entity first if you only have a name'). It also includes multiple example prompts to trigger this tool.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is covered. The description adds limited behavioral context by specifying the action targets 'previously stored memory' and mentions 'clear sensitive data,' but it doesn't go beyond what annotations imply. 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 sentences, front-loaded with the action verb. Every clause adds value—states what it does, when to use, and related tools. 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 simple one-parameter tool with no output schema, the description is sufficient. It covers purpose, usage scenarios, and the relationship to siblings. Annotations handle safety, so nothing critical is missing.

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

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

Schema description coverage is 100%, with the parameter 'key' already described as 'Memory key to delete.' The description's 'by key' only echoes the schema, adding no new semantic information beyond what's structured. 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 action: 'Delete a previously stored memory by key.' This is a specific verb and resource, and it distinguishes the tool from siblings like 'remember' and 'recall' by explicitly positioning it as the deletion counterpart.

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 when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names related tools ('Pair with remember and recall'), offering clear contextual guidance without excluding 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 cover readOnly, idempotent, and openWorld hints. The description adds valuable behavioral context: it explicitly states the tool 'fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format,' and that the output is 'a single text blob ready to drop at site-root/llms.txt.' This goes beyond the annotations by describing the internal process and output 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 concise and well-structured: first sentence states the primary function, second explains the process/output, third lists use cases. Every sentence provides value 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?

Given the tool's moderate complexity (fetching a URL, extracting content, generating a text file), the description is complete. It covers the purpose, process, output format, use cases, and all parameters are described in the schema. The lack of an output schema is compensated by the explicit statement that the output is a single text blob.

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 both parameters have descriptive comments (url: 'Full URL of the site to summarize', max_links: 'Maximum number of link entries to include (default 25, max 50)'). The description implicitly reinforces the url semantics via 'Fetches the page' but adds no extra 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 opens with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It clearly states the tool's function (fetches page, extracts title/description/key links, emits markdown), which distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence that audit or check AI presence rather than generate a file.

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 concrete use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It gives clear context for when to use the tool, but does not explicitly mention alternatives or when not to use it, which would merit a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds minimal behavioral context beyond that, such as the 'complete release list' hinting at potentially large responses, but it does not describe pagination or error behavior. This adds some value but is 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?

Two sentences, front-loaded with the action and content, followed by a necessary prerequisite. There is zero redundant phrasing, and every word adds value. The structure is optimal for quick parsing.

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

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

With only one parameter, an output schema present, and comprehensive annotations, the description covers all essential context for a simple get-by-id tool. The only slight shortfall is not naming close siblings (e.g., get_release) to prevent misuse, but the purpose is sufficiently distinct.

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

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

The schema already provides 100% coverage with a description for the id parameter ('MusicBrainz artist ID (UUID)'). The description adds contextual provenance by stating the ID comes from search_artists, which helps the agent understand how to obtain it. This goes beyond the schema's static definition.

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

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

The description clearly states the verb 'Get' and resource 'artist details', enumerating specific contents (biography, country, founding date, complete release list). This distinguishes it from sibling tools like get_release and search_artists. The explicit reference to requiring an artist ID from search_artists further disambiguates its 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 specifies a clear prerequisite: an artist ID must come from search_artists, implying this tool is for retrieval after an ID is known. It does not explicitly state when not to use it or name alternatives, but the workflow hint provides actionable 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=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the specific data returned (track listing, credits, media formats, metadata), which goes beyond the schema and annotations. No contradiction 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 a single concise sentence that front-loads the core purpose and includes useful specifics without redundancy. Every phrase earns its place, and there is no filler or repetition of annotations.

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

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

Given the simple single-parameter input, rich annotations, and presence of an output schema, the description sufficiently covers all needed context. It states the prerequisite, the contents of the response, and the overall purpose, making the tool fully usable without additional information.

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 'id' parameter, which is fully described as a MusicBrainz release ID (UUID). The description reinforces this by mentioning the ID comes from search_releases, but adds no new semantic 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 uses a specific verb and resource ('Get release details') and lists concrete contents (full track listing, credits, media formats, metadata). It clearly differentiates from siblings like get_artist and search_releases by specifying the release-specific data and the prerequisite ID source.

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 states 'Requires release ID from search_releases,' which clearly indicates the intended workflow and when to use this tool (after obtaining an ID from search_releases). It does not explicitly name alternatives or exclusion conditions, but the usage context is clear and actionable.

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

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

Annotations already indicate read-only and non-destructive behavior, so the description adds value by revealing that it is scoped to the caller and lists only active subscriptions by default. It also enumerates the response fields (id, type, params, etc.), which is important since no output schema is provided. This goes beyond the annotation's safety profile without contradicting it.

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

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

The description is three sentences, front-loaded with the purpose, then the return fields, then usage context. Every sentence carries unique information: what it does, what it returns, and when to use it. No words are wasted.

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 low complexity (1 optional parameter, no output schema), the description covers essentials: it states the operation, scope, default behavior (active subscriptions), return fields, and practical use cases. Annotations cover safety and idempotency. Nothing crucial is missing 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?

The schema has one parameter, include_inactive, with full documentation ('Include cancelled subscriptions in the response (default false).'). The description mentions 'active subscriptions' which is consistent with the default, but it adds no new meaning beyond the schema's own description. With 100% schema coverage, baseline of 3 is appropriate.

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

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

The description begins with 'List the caller's active subscriptions,' which is a specific verb-resource pair with clear scope (caller's, active). It distinguishes from siblings like subscribe and unsubscribe by focusing on listing rather than mutating, and explicitly lists return fields, removing any ambiguity about what the tool does.

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

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

The description gives explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This clearly tells the agent when to invoke this tool (pre-subscribe review and pre-cancel id lookup) and indirectly references alternatives (subscribe and unsubscribe) by describing these actions.

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 enriches the neutral annotations (all false) with important behavioral details: the claim_token flow for follow-up, daily digest review, rate limit of 5 per day, and that feedback is free and doesn't count against quota. It also implies a persistent write operation (submission) without contradicting annotations.

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

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

The description is detailed and front-loaded with the core purpose, but it is quite lengthy. Still, every sentence contributes (token flow, rate limits, exclusions, roadmap signal), so it remains efficient for the amount of behavioral context needed.

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

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

Despite lacking an output schema, the description fully covers the tool's role, usage scenarios, non-goals, authentication (claim_token), rate limiting, and impact. It is complete for a feedback submission tool with nested context and multiple feedback types.

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 meaningful parameter guidance beyond the schema, notably 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which is critical for correct message content. It also clarifies the claim_token usage pattern in the main text.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly lists the feedback types (bug, feature/data_gap, praise) and distinguishes the tool from siblings by stating it is ONLY for tools served by this Pipeworx connection, contrasting with other MCP servers.

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 conditions for use: when a tool returns wrong/stale data, when a desired tool is missing, or for praise. It also gives a clear exclusion ('if the tool came from a different MCP server... file it with that server instead') and actionable guidance for identifying Pipeworx tools by name.

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 substantial behavioral context beyond the annotations: it states the data is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached for 5min-1h depending on the window. This gives agents crucial information about freshness, privacy, and reliability without contradicting the read-only, idempotent, and non-destructive 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 appropriately sized at three sentences, with the purpose front-loaded in the first sentence, followed by useful use cases and technical notes. Each sentence earns its place, and there is no redundant or fluff 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?

Even without an output schema, the description covers the return shape (top tools, packs, volume), the simplified data format (pack, tool, count), and the absence of PII. It also mentions caching behavior. For a simple one-parameter read-only tool, this is sufficiently complete 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?

The schema already fully describes the only parameter 'window' with an enum and explanation of short vs long window semantics, achieving 100% schema coverage. The tool description merely repeats the existence of a window without adding additional meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: returning top tools, top packs, and total call volume for what other AI agents are calling on Pipeworx. The verb 'returns' and specific resource ('top tools', 'top packs', 'total call volume') make it specific, and it distinguishes itself from siblings like discover_tools by focusing on aggregate trending data rather than individual tool discovery.

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

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

The description provides three explicit use cases (discovering hot data sources, confirming canonical tool choice, aligning use case with agent needs), which is clear context for when to use it. However, it does not explicitly mention alternative tools or provide 'when not to use' guidance, so it falls short of a 5.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds rich behavioral context: Jaccard similarity threshold, placeholder filter returning null when >20%, and the fill check with realizable edge ≤0 meaning 'do not trade it'. No contradictions.

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 long, the description is well-structured with bold section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the core purpose in the first sentence. Each paragraph adds essential 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?

No output schema exists, so the description documents the response shape (opportunities[], partition_check{}) and includes actionable edge-case warnings. Covers all modes, thresholds, and non-obvious implications, making it complete for a complex tool.

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

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

Schema covers both parameters with useful mode descriptions, but the description goes further: event mode walks child markets, checks date/threshold ordering, and computes partition_check; topic mode searches related events and flattens markets. Adds examples and behavioral nuances beyond schema descriptions.

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

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

The description opens with 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks' — a specific verb, resource, and methodology. It also distinguishes itself from the sibling tool by explicitly deferring custom sizing to polymarket_fill_risk.

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

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

Provides explicit mode selection: call with no args for `trending_scan`, pass `event` for single-event, or `topic` for cross-event scanning. Includes recommendations ('event (recommended for a specific market)') and explicit alternatives ('For custom sizing use polymarket_fill_risk').

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 readOnlyHint and idempotentHint annotations, the description goes far beyond by disclosing caching behavior ('Cached 1h at the KV level keyed on all knobs'), the 'rare-by-design' nature of the longshot segment, filter counters in _diagnostics to explain empty segments, and a 24h-move warning that 'your edge may already be in the price.' These are non-obvious behavioral traits that materially affect agent decision-making.

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 comprehensive, with clear sectioning (model families, knobs, response top-level, diagnostics, caching) and good front-loading of purpose. However, it contains many nested parentheticals and technical details that make it long and harder to parse quickly. Every sentence adds value, but the structure could be more scannable, so it earns a 3 rather than higher.

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 fully by detailing the response structure: by_segment fields, every opportunity's data (edge_pp_net, kelly_fraction, market liquidity/spread/volume, 24h move warning), plus fed_candidates/fed_note and _diagnostics with funnel counters. It also explains why segments might be empty, covering all relevant execution and interpretation context 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%, but the description adds critical context: it explains that min_partition_leg_kelly applies to per-leg Kelly inside top_legs because parent-level kelly_fraction_half is always 0 for partition arbs, and that min_kelly does not filter partitions. It also explains the rationale for slippage_pp (zero fees but 20-50bp book cost) and how tradeable-edge knobs interact. This is rich 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 opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further distinguishes three distinct segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), making it clear this is a discovery tool for pricing discrepancies, clearly separating it from siblings like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description states it is 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets,' providing clear usage context. It also explains when knobs like min_liquidity/max_spread_pp apply, but it does not explicitly reference alternative tools for exclusions or contrast with sibling tools. This earns a 4 rather than 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?

Despite strong annotations (readOnly, idempotent, non-destructive), the description adds substantial behavioral detail: 60-day snapshot TTL, cache-miss write behavior, gaps meaning no scan, decay computed from daily closes not intraday, and the signed edge_pp_net convention (negative = SELL YES). This far exceeds annotation coverage and gives the agent critical interpretive nuance.

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 tightly structured: purpose, args, response fields, limits. It front-loads the core question, uses caps for field names, and every sentence adds operational or behavioral context without filler. The formatting makes a dense payload skimmable.

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 documents the response shape (tracked[], expired[], snapshot_dates[]) and explains edge cases like gaps, TTL bounds, and median lifespan as a 'competition clock'. It is complete for an agent to invoke and interpret results without external docs.

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 clear parameter descriptions, so baseline is 3. The description mostly restates defaults ('days default 14 max 30', 'window default 1wk') and adds the concept of 'snapshot family' but no new syntax or constraints beyond what the schema already provides.

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

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

The description opens with 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and explicitly frames the question it answers ('how long has this edge existed and is it shrinking?'). This clearly names the resource (snapshots) and distinguishes it from sibling tools like polymarket_edges by focusing on temporal persistence rather than current edge values.

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

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

It gives clear context: use when needing edge history vs. current state, and defines when data exists (snapshots written on cache-miss, gaps). However, it doesn't explicitly name alternatives like polymarket_edges or state when not to use it, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, matching the description's read-only 'check' nature. The description adds substantial behavioral context beyond annotations: return fields (top_of_book, vwap_fill_price, slippage_pp, verdict), mode-specific behaviors (auto side selection), failure modes (thin_legs, forced_directional_risk), and the dominant loss mode (partial basket fills → unhedged directional position). No contradictions.

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 a one-sentence purpose, then clearly organized into SINGLE-MARKET and BASKET sections. Almost every clause adds new information (verdicts, per-leg fill detail, risk explanation). It is dense and uses uppercase labels for scannability, though the single giant paragraph could be more readable with line breaks; still 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?

Despite having no output schema, the description enumerates all expected return values for both modes: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, and forced_directional_risk. It also covers edge cases like partial fills and auto side selection, making the tool fully predictable to an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful mode-specific semantics: for size_usd it clarifies 'max spend on buys, target proceeds on sells' in single-market and 'settlement notional S' in basket mode; for side it explains default auto in basket mode. This goes beyond the schema's generic parameter descriptions, justifying 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 opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' clearly distinguishing this from sibling tools like polymarket_arbitrage and polymarket_edges. It then enumerates both single-market and basket modes with specific inputs and outputs, leaving no ambiguity about what the tool does.

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

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

Provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround is not capturable, partial fills create unhedged risk). It also distinguishes when to use single-market vs basket mode, which is exactly the context an agent needs.

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

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

The description discloses numerous behavioral nuances beyond the annotations: compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0 vs both >5 legs), temporal_alignment semantics, and skipped_cross_type/subtype counters. It explains how matching works and warns when spreads may be meaningless. This far exceeds the minimal readOnlyHint/openWorldHint annotations.

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

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

The description is long and dense, but every section adds critical operational detail. It front-loads the core purpose and flows logically into modes, response format, and safety fields. However, it could be better structured with lists or paragraphs for readability, and some redundancy exists (e.g., repeated clarification of skipped_cross_type conditions).

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 has no output schema and 3 optional parameters, the description carries complete responsibility for explaining return values and edge cases. It does so thoroughly: describes leg-by-leg prices, spread computation (Kalshi − Polymarket), temporal alignment, compatibility warnings, and skip counters. The description is sufficient for an agent to invoke the tool correctly and interpret results.

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

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

The input schema already describes all three parameters, but the description adds meaning by explaining how parameters interact: explicit tickers override topic-mapped sides, and it details response semantics like spread[].top_spreads_pp and compatibility_warning conditions. This provides value far beyond the schema descriptions.

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

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

The description clearly states the tool's function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It names the specific source venues, the object (spread), and the action (comparing/synthesizing). It distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue comparisons.

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

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

The description explains two usage modes: 'topic' shortcuts and explicit tickers, with clear instructions for when to use each. It also provides a caution that 'pre-mapped ≠ tradeable' and that 'real cross-venue spreads are rarer than the macro-shortcut list suggests.' However, it does not explicitly name alternative tools or contrast with them, so it falls slightly short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds valuable behavioral context by explaining scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the list-all-keys mode. It doesn't cover failure modes or rate limits, but these are not essential given the annotations and tool simplicity.

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, each earning its place: the first states the core functionality, the second gives usage context and examples, the third explains scoping and siblings. It is front-loaded with the main action and avoids fluff. No unnecessary information is included.

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 (1 optional parameter) and the annotations are rich, so the description does not need to cover extensive edge cases. It includes the essential behaviors (get and list), scoping, and relationship to related tools. The presence of an output schema is not needed because the return values are either a single value or a list of keys, which is implicitly understood. The description is complete for its 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% because the only parameter, 'key', is fully described in the schema as 'Memory key to retrieve (omit to list all keys)'. The description effectively repeats this information ('Retrieve a value previously saved via remember, or list all saved keys (omit the key argument)') without adding new parameter-level details. The examples in the schema provide additional clarity, but the description doesn't go beyond baseline coverage.

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

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

The description opens with a specific verb 'Retrieve' and resource 'a value previously saved via remember', and clearly states the alternative behavior of listing all keys when the key argument is omitted. It distinguishes itself from sibling tools remember (save) and forget (delete), and provides concrete examples of stored context. This is a precise, unambiguous purpose statement.

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 the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names the sibling tools as alternatives: 'Pair with remember to save, forget to delete.' This gives clear direction on when to use recall versus other tools in the same family.

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?

Description explicitly mentions that setting mark_read:true flags returned events read, implying a state change. This contradicts the readOnlyHint=true annotation, which asserts the operation is read-only. Thus the description contradicts the annotation, requiring a score of 1.

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

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

The description is compact and front-loaded. Each sentence earns its place: purpose, payload, filtering, mark_read behavior, and alternative access. 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?

Given the tool's moderate complexity (5 optional params, no output schema), the description adequately covers the essential context: what events it returns, filtering, polling, and alternative access. It doesn't detail all params (limit, unread_only), but the schema fills that gap. The main shortfall is the annotation contradiction, which affects interpretation.

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

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

Schema already provides 100% parameter coverage, but the description adds value by explaining the mark_read side effect, giving an example type ("sec_8k"), and clarifying the return payload—meaning beyond the schema's parameter 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: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed), the action (pull), and the return payload (source, citation_uri, raw event payload), distinguishing it from potential siblings.

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

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

Provides clear context for when to use the tool, including filtering by type/since, the mark_read behavior for polling, and an alternative REST endpoint for scripts/dashboards. It doesn't explicitly state when not to use it, but the guidance is sufficient.

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, open-world, idempotent, non-destructive. The description adds significant behavioral context beyond annotations: fan-out to multiple APIs (SEC, GDELT, GNews, USPTO), GDELT→GNews fallback on rate limits/5xx, and USPTO soft-fail due to API sunset. These operational details are transparent and consistent with annotations.

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

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

The description is dense but efficiently structured: use-case phrases, core function, fan-out details, parameter format, return structure, and alternative tool. No redundant sentences; each segment contributes unique information. It is front-loaded with purpose 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 complex tool with no output schema, the description covers all critical aspects: sources (SEC, GDELT/GNews, USPTO), fallback behavior, `since` format, return shape (changes[], total_changes, citation URIs), and a clear alternative tool. The level of detail is 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?

Although the schema covers all parameters, the description adds practical meaning beyond schema: `since` accepts ISO or relative shorthand with examples, and `value` can be a ticker or CIK. It also gives usage guidance ('Use 30d or 1m for typical monitoring') and explains how `since` drives the fan-out, enriching the schema's bare definitions.

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

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

The description clearly states the tool's purpose: a change feed for a company in the last N days/weeks/months, aggregating SEC filings, news, and patents. It uses specific verbs and resource ('change feed') and distinguishes itself from entity_profile by explicitly stating when to use that sibling instead. Examples like 'What's new with X' further clarify intent.

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

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

Provides explicit when-to-use guidance: use for time-window change queries, and use entity_profile for static profiles regardless of window. It also recommends typical `since` values ('30d' or '1m') and explains the fallback behavior, giving clear context and exclusions.

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

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

The description discloses persistence semantics (authenticated vs. 24-hour anonymous retention) and scoping by identifier, which go beyond the annotations' idempotentHint and readOnlyHint. It 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 compact with no redundant sentences. It front-loads the core purpose and then efficiently adds use cases, storage characteristics, and sibling pairing.

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 two-parameter tool with no output schema, the description covers when, why, and what happens to stored data, plus how to retrieve/delete. It could mention return behavior, but the simplicity makes this a minor gap.

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

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

The schema already covers both parameters fully (100% coverage) with descriptions and examples. The description adds usage context but no new parameter semantics beyond what the schema provides, so a baseline 3 is appropriate.

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

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

The description uses the specific verb 'Save' and identifies the resource as data for reuse across conversations/sessions. It distinguishes from siblings by explicitly noting 'Pair with recall to retrieve later, forget to delete.'

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 concrete when-to-use scenarios ('a resolved ticker, a target address, a user preference') and explicitly names the alternatives for retrieval and deletion, giving the agent clear decision guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral detail beyond these: identifiers are labelled with their source, unresolved identifiers are explicitly stated under `unresolved`, and LEI/FIGI enrichment degrades gracefully if upstream sources are unavailable. 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 lengthy but dense with useful information: query examples, supported entity types, identifier sources, and failure behavior. Every sentence contributes to selection or invocation understanding, though the paragraph format could be slightly more structured for easier parsing.

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

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

Given the tool's complexity (two entity types, multiple identifier sources, fallback behavior) and lack of an output schema, the description covers use case, parameters, output content, and partial-failure behavior well. It does not, however, specify the exact response shape or how multiple matches are handled, leaving some ambiguity 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 input schema already has 100% coverage with clear descriptions for both parameters. The description enriches this by providing concrete value examples (AAPL, 0000320193, 'ozempic') and explaining type-specific behavior, adding semantic value beyond the schema.

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

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

The description states clearly that the tool resolves user-spoken names into canonical identifiers required by other tools, with explicit examples ('What's the ticker for…', 'find the CIK for…'). It distinguishes itself from sibling tools by positioning it as the initial lookup step that supplies identifiers to other tools.

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

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

The description gives an explicit directive: 'Use FIRST whenever you have a name but need an ID.' It also notes that using resolve_entity replaces 2-3 manual lookups, providing strong context for when to invoke. However, it does not mention exclusions or directly compare against alternative 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 this as a safe, idempotent read operation. The description adds valuable behavior beyond that: it explains that the tool probes each entity via ai_visibility_check, ranks results by score, and surfaces the most/least recognized, along with the return format. 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?

Three sentences, front-loaded with the core function, and every sentence adds value. It includes purpose, method, use case, and output format without any 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 moderate complexity, full annotation coverage, and complete schema, the description covers the key aspects: what it does, how it works, when to use it, and what to expect in the output. No output schema exists, so the description's mention of the ranked list with score/confidence/signal density compensates reasonably.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining 'entities' as 'your brand + N competitors' and noting that the first entry is treated as a subject, which is not in the schema. This helps the agent understand how to construct the parameter values.

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

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

The description clearly states the verb 'Compare' and the resource 'AI visibility across multiple entities side-by-side'. It distinguishes itself from the sibling tool ai_visibility_check by emphasizing the multi-entity comparison and ranking, making the purpose unmistakable.

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

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

The description provides clear context for when to use the tool ('competitive AI-marketing audits') with a concrete example query. It does not explicitly exclude alternatives or name when-not-to-use, but the comparison focus is clear enough to guide selection.

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

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

Adds significant behavioral context beyond the readOnly/idempotent annotations: it is a composite fan-out call, partial failures degrade gracefully, bundlephobia's first measurement on a new version can take 5–30s, and the sources_failed field will identify timeouts. This level of disclosure is genuinely useful for an agent deciding whether to invoke and how to interpret results.

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 a single line but every sentence earns its place. It is front-loaded with the core purpose, then efficiently covers usage, return fields, ecosystem scope, and failure behavior. There is no redundant text or filler; each clause contributes unique, actionable 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?

Given the tool's composite nature and the absence of an output schema, the description fully covers what the agent needs: it lists the exact summary fields, per-advisory detail, links, and alternative versions. It also explains timing risk, graceful degradation, and ecosystem limitations, making the tool self-contained from a documentation standpoint.

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

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

Schema coverage is 100%, so both parameters (package and version) are already fully described with types and defaults in the input schema. The description reinforces that package is an npm name and version defaults to latest, but adds no new semantics beyond what the schema already provides, matching 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 opens with a specific composite check: 'should I add this npm package to my project' and names the exact upstream sources (deps.dev and bundlephobia). This clearly distinguishes it from sibling tools and gives the agent a precise mental model of the tool's action and resource 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 triggers are provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states a clear exclusion and alternative: non-NPM ecosystems should fall under deps.dev:version directly, giving the agent explicit guidance on when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well-covered. The description adds value by specifying the output shape (IDs, names, types, countries) and referencing get_artist for deeper details. It does not mention pagination or rate limits, but for a simple read-only search this is adequate.

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

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

The description is two sentences: the first states the action and result, the second directs to the sibling tool. It is front-loaded and contains no redundant or filler information.

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

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

For a simple search tool with two parameters, detailed schema descriptions, a safe read-only annotation set, and an output schema available, the description provides all necessary context: what is searched, what is returned, and when to use a more detailed tool. No important gaps remain.

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

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

The input schema already provides full descriptions for both parameters (query and limit), including the default for limit. The description adds no additional parameter-specific guidance. With schema coverage at 100%, the baseline of 3 is appropriate.

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

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

The description clearly states the action ('Search for music artists by name') and the resource (music artists), and lists the specific output fields (artist IDs, names, types, and countries). It also distinguishes the tool from the sibling get_artist by pointing out what get_artist provides, making the purpose unmistakable.

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

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

The description explicitly directs users to 'Use get_artist to fetch full discography and biographical details,' which clarifies when to choose this tool over a sibling. This provides a clear alternative and implies that this tool is for basic artist lookup, even though it does not explicitly mention search_releases.

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 return fields (release IDs, titles, artists, dates, formats) and search criteria (title or artist), but no further behavioral context such as pagination or rate limits.

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

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

The description is two concise, front-loaded sentences with no redundant information. Every word earns its place, making it easy for an agent to parse quickly.

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, the rich annotations, and the presence of an output schema, the description is complete. It covers what is searched, by what criteria, and what fields are returned, which is sufficient for this straightforward search 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 parameters are well-documented. The description adds semantic value by explicitly mentioning 'title or artist name,' which clarifies the query parameter beyond the schema's 'Release title or search query.' This enriches parameter understanding.

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: 'Search for albums and releases by title or artist name.' It specifies the verb (search), resource (albums/releases), and scope (by title or artist), which distinguishes it from sibling tools like search_artists.

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 that this is for searching releases, but it does not explicitly name alternatives or when-not-to-use scenarios. Since the purpose is unambiguous, an agent can infer when to use it, though the exclusion guidance is lacking.

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/non-destructive, so the bar is lower. The description adds substantial behavioral context: returns character offsets and similarity scores, uses BGE-base-en embeddings with cosine over overlapping windows, enforces a 200K-char cap, and flags truncation. These details go beyond the annotations without contradiction.

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

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

The description is front-loaded with the core purpose in the first sentence, then adds usage context, workflow, and technical constraints in subsequent sentences. No redundancy or filler; 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?

Given the absence of an output schema, the description compensates by specifying return format (passages with offsets and scores), input constraints (200K cap, truncation flag), and integration with a sibling tool. It is complete for an agent to decide when to use it and what 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%, so baseline is 3. The description enhances semantics with concrete examples of the 'text' parameter ('SEC 10-K body, an article, a long tool result') and query styles ('supply-chain risk', etc.), clarifying that 'text' is previously fetched content. This adds practical meaning beyond the schema descriptions.

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

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

The description states 'Semantic search INSIDE a fetched record' with a specific verb and scope, and details the output: 'top-N passages with character offsets and similarity scores'. It clearly distinguishes itself from siblings by naming ask_pipeworx_grounded as a complementary tool and positioning itself as the retrieval step, not the answer generator.

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 'Use when the record is too big to cram into the prompt' and explains the benefit (saves context, returns only relevant passages). It also names a direct alternative, ask_pipeworx_grounded, and outlines the workflow: fetch with the gateway, then ground over passages. This is clear when-to-use guidance with an explicit alternative.

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

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

Beyond the annotations, the description discloses OAuth requirements, persistence restrictions, return value, delivery behavior (feed always on, email/sms/webhook), SMS verification and 10/day cap, webhook HMAC signing details, and auto-disable after 10 failures. 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 front-loaded with the core purpose and remains information-dense without filler. Despite being long, each clause about types, examples, and delivery channels earns its place given the tool's complexity.

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

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

The description covers authentication, supported types (with examples), delivery channels, and the return value, making it nearly complete for a subscription-creation tool. It omits two schema types from the narrative, but the schema fills that gap, and the absence of an output schema is mitigated by the explicit return of the subscription id.

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

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

Although schema coverage is 100%, the description adds concrete examples for type-specific parameters (e.g., items:['5.02'] = officer change, topic:'fed', series_id:'UNRATE') and clarifies delivery semantics (verified phone, cap, webhook signing). The only small gap is that patent_grant and clinical_trial are not mentioned in the narrative, but the schema fully documents them.

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 creates a proactive monitoring subscription to a live-data event stream and explicitly returns the new subscription id. This specific verb+resource phrasing distinguishes it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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 strong usage context: requires a Pipeworx OAuth account, anonymous/BYO cannot persist subscriptions, supported subscription types with examples, and delivery channel options including always-on feed and optional email/sms. However, it does not explicitly contrast with alternative tools or state 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 readOnly, idempotent, openWorld, and non-destructive behavior. The description adds that the tool draws from a live catalog of thousands of tools and returns example questions with exact tool and argument shape, plus topic filtering. This goes beyond the annotations by clarifying the dynamic, catalog-driven nature of the response.

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 strictly needed but front-loads the most important trigger phrases and purpose. Each sentence contributes distinct information: trigger examples, return structure, call variants, and when to use it first. It earns its length, though it could be tightened slightly without losing clarity.

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

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

For a tool with a single optional parameter and no output schema, the description is complete: it covers what the tool returns, how to invoke it, when to use it, and how it relates to other meta-tools. The context signals and sibling list confirm the tool's role, and the description leaves no significant gaps in behavior or use cases.

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

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

Schema coverage is 100% for the single optional `topic` parameter, and the description reinforces the 'omit for full spread, pass topic to focus' behavior. The description adds a few extra examples (e.g., finance, pharma, betting) but largely mirrors the schema's enum list. With high schema coverage, the baseline of 3 is appropriate; the description adds marginal but not substantial new semantic value.

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 this is the onboarding entry point for discovering what to ask Pipeworx, returning category-bucketed example questions with the exact tool and argument shape. It distinguishes itself from siblings like discover_tools and ask_pipeworx by emphasizing its role as a suggestions/ideas generator rather than a direct query or discovery tool.

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

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

Explicit usage guidance is provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and for learning to call meta-tools. It also explains call variants—no arguments for the full spread vs. passing a topic to focus—and offers concrete trigger examples like 'give me ideas' and 'show me examples.'

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 (non-destructive, idempotent), the description adds crucial behavioral detail: ownership enforcement (can only cancel your own), deactivation instead of deletion, and the downstream effect on recent_alerts. This gives the agent a clear mental model of side effects.

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 sentences each carry distinct information: the core action, the ownership rule, and the deactivation behavior. The purpose is front-loaded, and there is no redundant text.

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

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

For a one-parameter tool with no output schema, the description thoroughly covers what the agent needs to know: intended use, access control, lifecycle semantics, and relationship to recent_alerts. The behavior is fully explained without requiring additional documentation.

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

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

Schema coverage is 100% and the parameter description already explains 'id' as the subscription uuid from subscribe. The tool description repeats 'by id' without adding new semantic detail, so it meets the baseline but adds no extra value.

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

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

The description opens with 'Cancel a subscription by id', a specific verb+resource pairing that clearly distinguishes it from siblings like subscribe and list_subscriptions. The ownership constraint further sharpens the 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 implies usage: use this tool to cancel your own alert subscriptions. It does not explicitly name alternatives or exclusion conditions, but the ownership note provides context for when the 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses critical behavioral nuances: the meaning of each verdict, the distinction between 'could_not_verify' (check did not happen) and 'unsupported' (no source exists), and the presence of verification_error{stage,detail}. It also mentions the internal routing and the 'replaces 4-6 sequential calls' efficiency, which annotations do not cover.

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 tightly packed with essential info: start triggers, routing logic, return values, and error handling. It is front-loaded with example queries. Every sentence earns its place, though it could be slightly trimmed without losing meaning.

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

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

Given the tool's complexity and lack of an output schema, the description is exceptionally thorough. It explains all possible verdicts, that the response includes a grounded/structured actual value with a citation and reasoning, and clearly distinguishes 'could_not_verify' from 'unsupported' with error semantics. This fully equips the agent to interpret and use results correctly.

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

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

Schema coverage is 100% for both parameters, but the description adds valuable semantics: for tolerance_pct it explains the default is implied by wording with a cap of 5, and suggests setting 1-2 for hallucination detection. It also provides concrete examples for the claim parameter, enhancing 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 verifies natural-language factual claims against authoritative sources, using specific trigger phrases like 'is it true that' and 'fact check'. It distinguishes itself from sibling tools by explaining its unique dual-path routing (SEC EDGAR/XBRL for financial claims, grounded pipeline for everything else).

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and gives examples of user intents. It also clarifies what situations each path handles (company-financial vs. other claims), though it does not explicitly name tools to avoid in favor of this one.

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