science

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

With readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false already provided, the annotations cover the safety profile. The description adds valuable behavioral context by disclosing that probing Anthropic incurs direct costs ('you pay Anthropic directly') and that the _apiKey is passed straight through to api.anthropic.com. It also specifies the return payload structure (per-model score, confidence, signals, raw_response + combined view), which is useful given no output schema.

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

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

The description is exactly three sentences, front-loaded with the main action and output format. Every sentence adds necessary detail (default model, BYO key behavior, return structure, use cases) without redundancy or fluff.

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

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

Given the tool's moderate complexity (4 params, no output schema), the description is remarkably complete. It explains the core functionality, the default behavior, the optional Anthropic path with cost implications, the return fields, and common use cases. Combined with the rich annotations and fully described schema, the agent has everything essential to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches understanding by noting the default model (Workers AI Llama-3.3-70b) and clarifying that including 'anthropic' in models requires the _apiKey. This adds context beyond the schema's dry parameter descriptions, particularly for the 'models' and '_apiKey' parameters.

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

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

The description opens with a specific action ('Probe one or more LLMs for what they know...') and clearly defines the primary output ('score visibility (0-100) per model'). It distinguishes itself from sibling tools by focusing on AI visibility scoring across multiple models, with concrete use cases like AI-marketing audits and brand checks. The name and title align well, and the description provides specifics such as the default model and return structure.

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 ('Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the optional Anthropic integration scenario with BYO key. However, it does not explicitly mention when not to use it or name any sibling alternatives, so it falls short of the highest bar.

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. The description adds useful behavioral context: routing across 5,564 tools, filling arguments, returning stable pipeworx:// citation URIs, one fast call, works on every tier. No contradictions, and it doesn't need to repeat safety info already in annotations.

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

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

Front-loaded with 'PREFER OVER WEB SEARCH' and structured with clear examples and alternatives. The description is long but each sentence earns its place—usage guidance, scope, examples, and step-up logic. Slightly verbose, but not rambling.

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

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

With no output schema, the description explicitly states it returns a structured answer with stable pipeworx:// citation URIs. It covers purpose, scope, examples, alternatives, performance characteristics, and tier behavior. The description is self-sufficient for an agent to know when and how to invoke the tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds semantic value by specifying the kind of questions accepted (e.g., 'what is', 'look up', 'current') and providing concrete examples like 'current US unemployment rate'. This goes beyond the schema's bare 'Your question or request in natural language.'

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: routing questions to 5,564 tools across verified sources and returning structured answers with citation URIs. It uses a specific verb ('routes', 'returns') and distinguishes itself from siblings by explicitly mentioning ask_pipeworx_grounded and deep_research as alternatives for specialized cases.

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: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', 'START HERE for most questions', and step-up scenarios for ask_pipeworx_grounded and deep_research. Also covers edge cases like breaking-news and notes it's the default entry point.

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

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

Annotations already declare the tool as read-only, idempotent, and open-world. The description adds crucial behavioral context beyond these: the beta status, the fact that no candidate routing improvement is currently active (making it identical to ask_pipeworx right now), and that it is a full working router rather than a stub ('falls back to nothing'). This enriches the agent's understanding of runtime 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 composed of three sentences, each adding distinct value: purpose/status, usage instruction, and reassurance of full functionality. It is front-loaded with the key fact (beta) and avoids redundancy. Slightly long for a simple router but justified by the need to explain the experimental context.

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 a single question parameter, no output schema, and rich annotations, the description covers all essential aspects: what it does (universal router), how to use it, the current state (no active candidate), and its relationship to the stable version. It also addresses potential concerns about reliability ('full working router'). The description 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?

Schema coverage is 100% with all aliases documented for the 'question' parameter. The description does not add new parameter-level meaning beyond what the schema provides. It mentions 'same arguments' but doesn't elaborate on any specific parameter behavior, so baseline score of 3 is appropriate since the schema already fully describes the single parameter and its aliases.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx with identical routing capabilities and experimental improvements. It explicitly states it's the same universal router with the same tools and arguments, differentiating it from the stable ask_pipeworx. This makes 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?

Provides explicit usage instruction: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the context of how results are compared against the stable router, clarifying when this beta should be chosen. The guidance is direct 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals critical behavior: it extracts answers only from tool results, returns a verbatim evidence quote, and provides explicit refusal_reason values. This materially enhances what annotations alone convey and does not contradict 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 detailed but every sentence earns its place: it explains the mechanism, the return shape, refusal reasons, use cases, and trade-offs with ask_pipeworx. It is front-loaded with the key differentiator and remains structured 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?

Even without an output schema, the description fully documents the success response structure, refusal response structure with specific reason codes, and the operational cost. It also covers when to use this tool versus its cheaper sibling, making it complete for high-stakes usage.

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

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

Schema coverage is 100%, with all six parameters being aliases for the single natural-language question. The description adds no new parameter semantics beyond what the schema already provides, so 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 this is a hallucination-resistant answer mode that routes to tools, fetches data, and extracts answers only from tool results. It explicitly contrasts with ask_pipeworx by emphasizing grounded evidence and structured refusals, distinguishing it from its sibling tools.

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

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

It gives explicit when-to-use guidance: whenever an answer will be quoted, cited, or acted on and facts must not be invented, with concrete examples like financial verdicts and legal claims. It also names the alternative ask_pipeworx and provides a preference rule: use the grounded version only when needed because it costs an extra LLM call.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, but the description goes far beyond by documenting parallel fan-out, classification behavior, blocking statuses for low-confidence/closed markets, illiquidity flags, resolution-rule risk, and news fallback fields. This gives the agent a precise mental model of internal behavior and edge cases.

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

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

The description is long but highly structured with CAPITALIZED section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.), making it scannable. Every section carries operational value, though a trim of repetitive examples could improve conciseness.

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

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

Without an output schema, the description fully documents response shapes, resolver contract, parent event extraction, news fallback semantics, and safety statuses. It covers tradeability warnings and cancellation-rule risk, ensuring agents have complete contextual information for safe usage.

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

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

Schema coverage is 100%, and the schema already explains that market accepts a slug, URL, or question text; depth has an enum; and include_raw controls summarization. The description adds examples of fan-out but does not add new meaning beyond the schema, so a 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 opens with a specific verb-resource pair ('Research a Polymarket bet by pulling the relevant Pipeworx data') and clearly distinguishes from siblings by specifying its use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). It also outlines classification and fan-out behavior, leaving no ambiguity about what this tool does.

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

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

Explicitly states 'Use for' with concrete query types and provides a detailed resolver contract instructing agents to always inspect match confidence before trusting analysis. Also warns when not to trust (low-confidence, closed markets) and when to check cancellation rules before sizing bets. However, it does not explicitly name alternative sibling tools, so it stops short of a perfect score.

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

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

Annotations provide safe read-only profile, but description adds substantial behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return format with citation URIs. 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?

Description is dense but well-structured, starting with trigger phrases and then layering usage, data details, and output. It is longer than minimal but every sentence contributes; slightly verbose with 'Replaces 8–15 sequential lookups' but that's useful context.

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 explains return contents (paired data + citation URIs) and the metrics computed. It covers data sources, fiscal-year handling, sorting, and entity constraints, making it complete for an AI agent to select and invoke.

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, but description enriches meaning by explaining what each 'type' pulls (company financials vs drug regulatory data) and how 'values' are used (tickers/CIKs vs drug names). This goes far beyond the schema's enum and array descriptions.

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

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

Description explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call', identifying specific verb and resource. It also provides example utterances like 'X vs Y' and 'rank these companies', distinguishing it from single-entity tools like entity_profile.

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?

Gives explicit trigger examples and states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', clearly directing when to use the tool. It also clarifies that it replaces 8–15 sequential lookups, giving a comparative advantage over alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds substantial behavioral context: account requirements, parallel routing across 5,564 tools, gaps[] for unanswered facets, no invented answers, citation_uri resolvability, contradictions[] output, semantic excerpting, and expected latency. This far exceeds what annotations provide.

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

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

The description is information-dense but long and written as a single unbroken paragraph, making it harder to scan. It front-loads the account requirement, which is useful, but many details (citation behavior, excerpting mechanics) could be structured into bullets. Every sentence earns its place, but the lack of formatting hurts 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?

Despite no output schema, the description thoroughly explains return values: findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop fields, and handling of large records. For a tool with two parameters and no nested objects, this is remarkably complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description enriches semantics by explaining how depth levels affect hops and contradiction scanning, and clarifying that question can be broad/multi-part. Since the schema carries the load and the description adds meaningful context, a 4 is warranted.

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

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

The description clearly states the tool is a grounded multi-source research tool over Pipeworx's structured data sources, explicitly contrasting with open-web search and naming sibling alternatives. Specific examples like 'compare X and Y's regulatory + financial exposure' and mention of decomposition/parallel routing make its purpose concrete and distinguishable from siblings.

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

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

Provides explicit when-to-use guidance (broad/multi-part questions over structured data), when-not-to-use (single lookups or breaking/current-news topics), and names alternatives (ask_pipeworx for single lookups and live news). Also explains depth levels and second-hop iteration, giving clear selection criteria.

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

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

Annotations already provide readOnlyHint and idempotentHint. The description adds valuable context about return format (names, descriptions, full schemas, curated examples) and the direct callability of results, which is behavior beyond what annotations convey.

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

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

The purpose is front-loaded in the first sentence, but the long enumerated list of data domains adds bulk. Still, every sentence serves a purpose and the structure is clear, so it's efficient though not perfectly concise.

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

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

With no output schema, the description fully explains what is returned (top-N tools with names, descriptions, full input schemas, curated examples) and provides enough usage context, making it complete 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 coverage is 100%, so the schema fully documents all parameters including aliases. The description's domain list adds flavor but doesn't change parameter semantics, placing it at the baseline for high schema coverage.

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

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

The description clearly states a specific verb+resource action: 'Find tools by describing the data or task.' It distinguishes itself from data-access siblings by explaining it returns top-N relevant tools with full schemas, making it a meta-tool rather than a data 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?

The description explicitly says to use this tool when browsing/discovering available tools and 'Call this FIRST when you have many tools available.' It implies a when-not ('not just one answer') but doesn't name specific alternative tools, so it falls short of full 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 mark this as read-only, idempotent, and non-destructive. The description adds substantial context: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), soft-fails for the deprecated USPTO PatentsView API, uses a GDELT→GNews fallback, and clarifies return field specifics. This goes well beyond the annotation safety profile.

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

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

The description is dense and information-rich, front-loading usage examples before the core explanation. It is a single long sentence but each clause earns its place—covering sources, return fields, fallbacks, and limitations. Minor structure improvement could break it into bullets, but it remains highly scannable.

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

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

Given the tool's complexity (multi-source fan-out, no output schema, fallback logic) and the absence of an output schema, the description thoroughly covers return values (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and edge cases (patent API sunset, name support, ticker/CIK formats). It is complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description reinforces the value format with concrete examples ('AAPL' vs '0000320193') and reiterates the 'names not supported' constraint, which mirrors the schema. While it doesn't add entirely new parameter meaning, the examples and zero-padding clarification make invocation more foolproof.

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 'full cross-source profile of a US public company in ONE parallel call' with a specific list of returned data. It uses a specific verb ('profile', 'brief', 'rundown') and distinguishes from siblings like resolve_entity by specifying inputs and scope. The examples ('tell me about X', 'research Acme') reinforce the intended use.

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 to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and provides a clear exclusion: 'names not supported (use resolve_entity first if you only have a name)'. This gives direct when-to-use and when-not-to-use guidance with an alternative tool named.

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 disclose destructive and non-read-only behavior. The description adds context that it is for clearing stale or sensitive data and pairs with remember/recall, which is useful beyond the structured hints. It does not contradict annotations.

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

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

The description is two sentences, front-loaded with the action, and then gives usage context and related tool pairings. Every word earns its place with no fluff.

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

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

For a simple one-parameter tool with annotations and no output schema, the description adequately covers what the tool does, when to use it, and mentions related tools. It lacks a note on return value or idempotency, but the annotations cover safety, and the use cases are explicit.

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 covers the sole parameter 'key' with description 'Memory key to delete' (100% coverage), so the description adds little semantic value. The phrase 'by key' is redundant with the schema, and no additional syntax or format details are provided.

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 'Delete a previously stored memory by key' with a specific verb and resource, clearly distinguishing it from siblings like remember and recall. It also explicitly mentions pairing with these tools to consolidate the purpose.

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

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

'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier' gives explicit context and trigger conditions. However, it lacks explicit when-not-to-use guidance or alternative tools (though it names complements), preventing a 5.

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

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

The description reveals the operational flow—fetching the page, extracting key elements, and emitting standard llms.txt markdown—which supplements the annotations. It also clarifies that the output is a text blob for site-root placement, adding practical context beyond the read-only/idempotent hints.

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

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

Three sentences cover purpose, process, output, and use cases with no redundancy. Each sentence adds distinct value, and the front-loaded first sentence immediately communicates the core function.

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 what the tool does, how it works, what it returns, and when to use it, which is sufficient for a two-parameter tool with good annotations. It lacks edge-case discussion (e.g., invalid URLs) but does not need to given the straightforward nature and schema coverage.

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

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

Schema coverage is 100%, with both `url` and `max_links` described in the input schema. The description adds minimal new parameter information; it only reinforces that the tool works 'for any URL' without detailing `max_links` semantics beyond the schema. Baseline of 3 applies.

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

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

The description clearly states the tool's function—generating a production-ready llms.txt file—and specifies the input (any URL) and the output format. It also distinguishes it from sibling tools by emphasizing the generation of the llms.txt standard, whereas siblings like scan_competitor_ai_presence likely focus on broader AI visibility analysis.

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

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

The 'Useful for:' section enumerates three concrete scenarios (client indexing, personal project, competitor audit), giving agents clear context for when to invoke the tool. However, it does not explicitly mention alternatives or exclusions, so it stops short of full comparative guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds context about what data is returned (US AQI, pollutants), but no additional behavioral traits such as rate limits, authentication, or limitations beyond what the schema states. 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 a single, front-loaded sentence that states the action, resource, and return values without any fluff or repetition. Every word earns its place.

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

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

The tool is simple, with annotations covering safety, an output schema covering return structure, and schema descriptions covering parameters. The description effectively covers the purpose and key outputs, making it complete for its complexity.

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

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

Schema description coverage is 100%, with both latitude and longitude fully described and examples provided. The description only says 'at a latitude/longitude', which adds no extra meaning beyond what the schema already provides. Baseline 3 applies.

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

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

The description uses a specific verb 'check' with resource 'air quality' and specifies the coordinate parameters. It clearly distinguishes from siblings by its unique domain, and the list of return values adds specificity.

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

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

The description provides clear context on when to use the tool (when you need current air quality at a latitude/longitude), but it does not explicitly mention alternatives or when not to use it. The schema adds 'does not geocode city names', which is a usage exclusion, but that is not in the description itself.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds that date is optional and that the response includes image URL/title/explanation, but it does not disclose behavior like what happens for an invalid date or rate limits. This is adequate but minimal beyond annotations.

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

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

Two concise sentences with no filler. The first sentence states the primary purpose and outputs, the second explains the optional parameter. Highly efficient and 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 simplicity (1 optional param, strong annotations, and an output schema), the description is complete enough. It omits edge-case behavior like invalid dates, but that is not critical for a read-only, idempotent single-resource tool. Slightly below perfect due to no mention of fallback or error handling.

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

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

Schema coverage is 100% with the date parameter fully described (format and default). The description repeats the format example '2024-01-15', adding no new meaning beyond the schema. Baseline 3 is appropriate when the schema handles parameter semantics.

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

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

The description clearly states the tool retrieves NASA's Astronomy Picture of the Day and lists the returned fields (image URL, title, explanation). It is specific and distinct from sibling get_* tools like get_air_quality or get_earthquakes.

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 when you need the APOD, optionally with a specific date. However, it does not explicitly state when not to use it or mention any alternative tools, leaving usage guidance implicit rather than explicit.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context: the external USGS FDSN service, the limit of 20 results, and the 1–30 day lookback constraint. 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?

Two sentences, front-loaded with the main action, and every clause contributes useful information (source, limits, filters, return fields). No redundant or filler content.

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

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

The tool is simple (2 optional parameters) and has both annotations and an output schema. The description covers return fields and key constraints, making it self-sufficient for an agent to understand what it will get and how parameters affect results.

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

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

Schema coverage is 100% and both parameters have descriptions in the schema. The description essentially repeats the schema's parameter info (defaults and ranges) without adding new semantics, so it meets 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 uses a specific verb ('Retrieve') with a clear resource ('globally recent earthquakes from the USGS FDSN service') and includes filtering criteria. It clearly distinguishes from sibling tools like get_air_quality and get_iss_location by specifying both the data type and source service.

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

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

The description clearly implies when to use this tool (when earthquake data is needed) and specifies the return fields, but it does not explicitly mention alternatives or exclusion cases. Context is sufficient for an agent to select it among siblings, though no direct contrast is provided.

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 safety (read-only, idempotent, non-destructive). The description adds value by revealing the external Open Notify API source and the real-time nature of the data, which are useful behavioral traits not captured in the annotations.

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

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

Two concise sentences that front-load the main purpose and include key notes on input and output. Every word earns its place; no filler or redundancy.

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

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

Given zero parameters, a comprehensive set of annotations, and an existing output schema, the description sufficiently covers the tool's function and constraints. It adds the important context of using an external API, which rounds out the picture.

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?

With zero parameters, the baseline is 4. The description explicitly reinforces this with 'No inputs required', and the empty schema confirms it. Nothing more is needed.

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 fetches the ISS's current latitude, longitude, and Unix timestamp from a named API, using a specific verb ('Fetch') and resource. This distinguishes it from all sibling 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 notes that no inputs are required and that it returns a real-time position fix, making the primary use case obvious. It doesn't explicitly mention alternatives or exclusions, but the tool's uniqueness in the sibling list makes that less critical.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds that it lists 'active subscriptions' and details the return fields, but does not describe any potential quirks such as pagination or authorization requirements. This is adequate, but not more than minimal.

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

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

The description is two sentences with no fluff. The first sentence states the action and return fields, the second gives usage context. It is front-loaded and efficiently earns its place.

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

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

For a simple read-only list tool with one optional parameter, the description provides sufficient context. It explicitly lists all returned fields, which compensates for the lack of an output schema, and the annotations cover safety behavior. The tool is straightforward to invoke correctly.

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

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

The schema already provides a full description for the single parameter (include_inactive), and schema coverage is 100%. The description's mention of 'active subscriptions' reinforces the default behavior, but does not add significant extra meaning beyond the schema.

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

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

The description clearly identifies the verb (List), the resource (the caller's active subscriptions), and explicitly enumerates the returned fields. It distinguishes itself from sibling tools like subscribe and unsubscribe through its focus on reviewing existing subscriptions.

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

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

The description provides clear context for when to use this tool: 'to review what you're monitoring before adding more or to find an id to cancel.' It implies alternatives (subscribe for adding, unsubscribe for canceling) but does not explicitly name them or state exclusions.

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

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

The description reveals key behavioral traits beyond the sparse annotations: filing without an account returns a `claim_token` that can be used later to read status, rate-limited to 5 per identifier per day, free, and doesn't count against tool-call quota. It also explains how feedback is consumed (daily digests, roadmap signal). 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 longer than typical, but every sentence carries operational significance: use cases, exclusions, token behavior, rate limits, and quota impact. It is front-loaded with the core purpose and then adds necessary detail. No wasted words, though it could potentially be tightened (e.g., combining 'team reads digests daily' and 'signal affects roadmap'—still acceptable).

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

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

Despite having no output schema, the description fully explains what happens after filing (claim_token returned, can be read back later, team reads daily). It covers edge cases (no account, rate limiting, non-Pipeworx tools) and provides complete instructions for correct usage. This is a complex tool with 4 optional parameters, and the description leaves no critical gaps.

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

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

Schema descriptions fully document each parameter (type, context, message, claim_token), so the baseline is 3. The description adds extra semantics by explaining the claim_token flow ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and clarifying that the message should 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names the resource (Pipeworx team) and the actions (report bug, feature, data_gap, praise), distinguishing it from all sibling 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 explicit when-to-use scenarios: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also explicitly excludes tools from other MCP servers: 'if the tool came from a different MCP server... file it with that server instead.' This is superior guidance.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses critical behavioral details: data provenance ('derived from CF analytics-engine'), privacy ('no PII'), output shape ('just (pack, tool, count)'), and caching ('Cached 5min-1h depending on window'). This gives the agent realistic expectations about data freshness and content.

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 tightly structured: a lead sentence stating what it does, a summary of output, and a numbered list of use cases. Every sentence adds value and there is no redundant filler, 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?

For a simple read-only tool with one optional parameter, the description fully covers the output contents, data source, privacy, and caching behavior. Since the return shape is described in plain terms ('top tools, top packs, and total call volume'), the absence of an output schema does not leave a 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 documents the single `window` parameter with an enum and a rich description (100% coverage). The tool description only briefly references the window options and adds minimal new parameter semantics, as the schema's parameter description already covers the trade-offs between shorter and longer windows.

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: 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d)'. It uses a specific verb ('Returns') and identifies the exact resource, distinguishing it from sibling tools by focusing on aggregate AI-agent usage rather than individual lookups.

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

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

The description provides three explicit 'Useful for' scenarios, giving the agent clear guidance on when to invoke this tool: discovering hot data sources, confirming canonical tool choice, and aligning with typical agent needs. However, it does not explicitly mention sibling alternatives 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 read-only, open-world, idempotent, and non-destructive. The description goes far beyond by disclosing the Jaccard similarity threshold (≥0.30), placeholder slug filtering (>20% returns null), fill check behavior against live CLOB depth, and the critical 'do not trade it' caveat when realizable edge is ≤0. No contradiction with annotations.

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

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

The description is long but every sentence earns its place. It is front-loaded with purpose, then structured into modes, semantic anchor, partition filter, response, and fill check. Semicolons and dense factual phrasing convey maximum information with zero fluff. For a tool with this complexity, the length is justified.

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

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

With no output schema, the description compensates by fully documenting return values: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and partition_check fields. It also explains fill check outputs (theoretical_edge_pp_at_book, realizable_edge_pp at 1000 shares/leg, thin_legs[]) and edge cases like null arb signals and skipped_low_similarity. This is exceptionally complete for a complex tool with 2 optional params.

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 substantial meaning: it provides concrete slug examples, explains that event mode 'walks child markets, checks date-axis / threshold-axis ordering AND computes the partition_check', and that topic mode 'searches related events across the platform, flattens markets, runs the comparator on the union'. It also defines the no-arg trending_scan, enriching both parameters far beyond the schema's simple descriptions.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from sibling tools by explaining its unique arbitrage-scanning approach and modes (trending_scan, event, topic). This is a textbook example of purpose clarity.

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 instructions are provided: 'Call with NO args for a trending_scan... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' It recommends event for specific markets and topic for cross-event, and explicitly points to polymarket_fill_risk for custom sizing, creating clear alternatives 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds valuable behavior context: 'Cached 1h at the KV level keyed on all knobs', diagnostics via '_diagnostics{...} so callers can see WHY a segment is empty', and the Fed exclusion note. 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 extremely long and dense, combining model-family internals, response structure, knobs, and diagnostics into one sprawling paragraph. It is not front-loaded; key operational details are buried in nested parentheses. While every sentence has content, the lack of structure hurts scannability for an agent deciding whether to call the tool.

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

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

With no output schema, the description thoroughly explains return values via 'RESPONSE TOP-LEVEL: by_segment{...}, fed_candidates/fed_note...', and '_diagnostics{...}'. It also covers caching and edge-case behavior, making it complete for a complex tool.

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

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

Schema coverage is 100%, but the description enriches many parameters with practical guidance. For example, min_partition_leg_kelly is explained as applying per-leg because 'Partition arbs always return kelly_fraction_half=0 at the parent level by design', and slippage_pp includes the tip that 'bid/ask + thin depth typically eats 20-50bp per trade.' These details go well 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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes it from siblings like polymarket_arbitrage (cross-market arbitrage) and polymarket_edge_tracker (tracking edges over time).

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 states a clear use case: 'Built for "what should I bet on today"' and mentions agents discover opportunities without paging hundreds of markets. However, it does not explicitly name alternatives or say when not to use this tool, 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?

Even with annotations declaring readOnly, openWorld, idempotent, and non-destructive behavior, the description adds substantial behavioral detail: snapshots are only written on cache-miss so gaps mean no scan; history is bounded by a 60-day TTL; decay is computed from daily closes not intraday; and edge_pp_net is signed by trade direction. This is exactly the kind of context an agent needs and goes well beyond the annotations.

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

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

The description is front-loaded with the core purpose, followed by structured Args, RESPONSE, and LIMITS sections. Although long, each sentence delivers unique information—no filler. The use of uppercase section labels and explicit field names makes it easy to parse.

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

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

With no output schema, the description fully explains the response structure: tracked[], expired[], and snapshot_dates[], including what each field means and how to interpret them. It also covers edge cases (gaps in snapshots, TTL limits, intraday vs daily closes). This makes the tool self-contained for an agent despite the lack of a formal output schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by explaining what 'days' and 'window' conceptually affect (lookback, snapshot family) and reiterating defaults/max values alongside the schema. It clarifies that 'window' refers to a polymarket_edges snapshot family, which enriches the schema's plain value list.

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

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

The description clearly identifies the tool as 'edge persistence and decay telemetry' built from daily polymarket_edges snapshots, with the specific question 'how long has this edge existed and is it shrinking?' This distinguishes it from sibling tools like polymarket_edges (which likely screens for edges) and polymarket_arbitrage.

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

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

The description provides clear usage context: it contrasts a fresh wide edge with a 3-week-old wide edge, implying this tool is for assessing edge persistence/duration. It does not explicitly name alternatives or state when not to use it, but the purpose is contextualized enough for an agent to choose it over siblings.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds behavioral detail about walking the order book ladder, returning specific fields like top_of_book, vwap_fill_price, slippage_pp, and forced_directional_risk, and warns about partial basket fills converting arb into unhedged directional position. No contradiction.

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

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

Description is longer but structured clearly into SINGLE-MARKET and BASKET sections, with all sentences adding value. The opening phrase states core purpose, and the detailed breakdown is warranted for a tool with two modes and many output fields.

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, description compensates by detailing return values (top_of_book, vwap_fill_price, slippage_pp, shares_filled, etc.) and mode-specific behavior. It also explains the risk logic and edge cases, making it complete for a read-only 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 description adds significant meaning: explains how size_usd is interpreted differently for single-market vs basket mode (spend vs settlement notional), and how side defaults are mode-dependent (auto for basket). This goes beyond schema descriptions, adding critical context.

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 states clearly 'Realizable-vs-theoretical edge check against live CLOB order-book depth' with a specific verb and resource. It distinguishes from siblings by focusing on fill risk and pre-trade validation, naming polymarket_arbitrage and polymarket_edges as related but different tools.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround on thin books is not capturable). This provides clear when-to-use and alternative context.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds extensive context: it explains response structure, leg-by-leg prices, the spread calculation, and the meaning of safety fields like compatibility_warning, temporal_alignment, and skipped counters. It also discloses limitations (most topics return warnings), going well beyond the structured annotations.

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

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

The description is long but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). The extra length is justified by the tool's complexity and the need to explain safety fields since there is no output schema. Every sentence adds value, though it could be tightened slightly.

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

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

With no output schema, the description fully explains the response format including prices, top_spreads_pp, and all safety fields. It covers temporal alignment, skipped type counters, and gives a concrete example of non-equivalent bet shapes. It also prepares the user for common edge cases and limitations, making it self-sufficient for a tool with 3 optional parameters.

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 adds meaning beyond the schema by explaining that 'topic' is a pre-mapped shortcut that auto-fetches matching events, and that the explicit fields override the mapped side. It also lists the 10 allowed topics, giving concrete context not present in the schema alone.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself with two modes (topic shortcuts vs explicit pairings) and explains the core output, making it distinct from sibling tools like polymarket_arbitrage.

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 explains when to use each mode: topic for 10 pre-mapped macros, explicit for custom pairings. It also provides clear exclusion criteria via compatibility_warning and temporal_alignment, plus a strong caveat that pre-mapped topics often are not tradeable. This effectively communicates when not to rely on the 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 readOnly, idempotent, and non-destructive behavior. The description adds valuable context: scoping to user identifier (anonymous IP, BYO key hash, or account ID) and the behavior of omitting the key to list all keys. 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 concise sentences, front-loaded with the primary purpose, followed by usage context and scoping. No redundant phrases; every sentence adds value.

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

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

For a simple one-parameter tool with no output schema, the description covers return behavior (value or list of keys), scoping, and relationship to sibling tools. It does not explicitly state error behavior (e.g., key not found), but that is not critical for completeness at this level.

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 adds meaning by explaining that the key refers to a value saved via remember, provides concrete examples (user_research_topic, address), and clarifies that omitting the key lists all keys—beyond the schema's brief description.

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

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

The description opens with a specific verb+resource ('Retrieve a value previously saved via remember') and clearly distinguishes the tool's two modes (retrieve by key or list all keys). It also differentiates from sibling tools like remember and forget by identifying the action as retrieval.

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

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

The description gives explicit context for when to use (look up previously saved context like target ticker or research notes) and pairs with remember/forget. It lacks an explicit 'when not to use' clause, but the guidance is clear and practical.

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

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

The description states 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' indicating a state-changing side effect. This directly contradicts the annotations readOnlyHint=true and idempotentHint=true, which assert no mutation and idempotency. The contradiction is significant.

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-sentence paragraph: first introduces the core action, then details return fields and filters, and finally explains mark_read and an alternative endpoint. Every sentence adds valuable context with no redundancy or filler.

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

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

For a tool with five optional parameters and no output schema, the description thoroughly covers essential missing context: the structure of returned events (source, citation_uri, raw payload), filtering options, stateful mark_read behavior, and the REST endpoint for programmatic access. It provides a complete operational picture.

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 with descriptions, the description adds practical semantics: type example 'sec_8k', clarification that since is an ISO timestamp, and the behavioral effect of mark_read. This goes beyond the schema's basic field descriptions, making parameter intent substantially clearer.

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 'Pull fired events from your subscription feed,' giving a specific verb and resource. It further specifies what the tool returns (most recent alerts with source, citation_uri, and raw payload), clearly differentiating it from siblings like recent_changes by its focus on subscription-fired 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?

The description provides concrete usage context: filtering by type and since, using mark_read for polling semantics, and noting the alternative REST endpoint for scripts. It does not explicitly name sibling alternatives or exclusions, but the guidance is clear and actionable for common use cases.

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

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

Beyond the readOnlyHint, openWorldHint, and idempotentHint annotations, the description discloses detailed behavioral traits: multi-source fan-out to SEC EDGAR, GDELT→GNews fallback on rate limit or 5xx, and USPTO soft-fail due to PatentsView API sunset. It also explains the parallel nature of the call.

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

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

The description is dense but well-structured, starting with natural-language examples, then the core definition, source details, and return format. It is longer than minimal but every sentence contributes useful information; no filler.

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

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

With no output schema, the description compensates by specifying the return structure: changes[] grouped by source, total_changes count, and pipeworx:// citation URIs. It also covers multi-source behavior, fallbacks, and date formats, making it self-contained for an agent.

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

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

Schema description coverage is 100%, providing a baseline of 3. The description adds extra meaning for `since` by detailing ISO date format and relative shorthand with examples, and clarifies `value` accepts ticker or zero-padded CIK. This pushes above baseline.

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

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

The description clearly defines the tool as a change feed for a company over a recent window, with concrete example queries. It explicitly contrasts with entity_profile, which returns a static profile, thus distinguishing it from a key sibling. The verbs 'fans out' and 'change feed' convey the action and 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 provides explicit when-to-use context (e.g., 'what's new with X', 'latest on Y') and names an alternative: 'Use entity_profile instead when you want the static profile'. This gives the agent clear guidance on tool selection.

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

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

Annotations already indicate this is a non-read-only, idempotent, non-destructive write. The description adds valuable context beyond annotations: key-value scoping per identifier, persistence differences between authenticated and anonymous sessions, and the 24-hour retention for anonymous sessions. This extra behavioral detail justifies above baseline.

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

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

Three sentences deliver purpose, usage context, storage semantics, and lifecycle pairing with zero redundancy. The most important information is front-loaded in the first sentence.

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

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

For a simple two-parameter key-value set operation, the description covers purpose, when to use, storage scoping, persistence behavior, and how it fits with related tools. No output schema is needed since the operation is a write, and no other behavioral details are essential.

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 descriptive parameter details for both 'key' and 'value' (including examples and allowed content). The description merely reinforces that storage is key-value without adding new semantic meaning, so baseline 3 applies.

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

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

The description opens with a specific verb and resource ('Save data the agent will need to reuse later'), clearly identifying the tool's function. It distinguishes from siblings by explicitly pairing with 'recall' and 'forget' and clarifies the key-value storage model.

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

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

It provides explicit when-to-use guidance with concrete examples ('a resolved ticker, a target address, a user preference, a research subject') and tells the agent to use it when avoiding redundant lookups. It also names the relevant sibling tools for retrieval and deletion, giving clear 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?

Description significantly extends annotations (readOnlyHint, openWorldHint, idempotentHint) by detailing internal cascading through multiple lookups, graceful degradation when sources are unavailable, labeling of each identifier with its source, and explicit reporting of unresolved identifiers. 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?

Description is relatively long but front-loaded with purpose and examples. Each sentence adds useful context (e.g., graceful degradation, unresolved handling). A minor reduction in wordiness could improve conciseness, but current length is justified by the tool's complexity.

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

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

Given no output schema, the description compensates by detailing the return structure (labeled identifiers, unresolved list). It covers supported entity types, input variations, and internal logic. However, it does not explicitly state the output format (e.g., JSON object) or mention limits/pagination, leaving minor gaps.

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

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

Schema coverage is 100%, and description adds substantial meaning: explains how 'type' determines resolution behavior (company vs. drug), details accepted input formats for 'value' (ticker, CIK, ISIN, name for company; brand or generic for drug), and describes what happens with ISINs via GLEIF mapping. This goes well 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?

Description starts with concrete example queries ('What's the ticker for…') and states the core verb ('resolve') and resource ('user-spoken NAME to canonical identifiers'). It explicitly positions itself as the tool to use 'FIRST whenever you have a name but need an ID,' clearly distinguishing its purpose from sibling tools like compare_entities or entity_profile.

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?

Description gives strong usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also lists many example queries and explains internal cascading behavior. However, it does not explicitly state when NOT to use this tool (e.g., if you already have an ID) or name direct alternatives, leaving a minor gap.

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 well beyond the annotations by explaining the internal process: it calls ai_visibility_check per entity, ranks by score, and surfaces most/least recognized. It also discloses the output structure (ranked list with score, confidence, signal density) and that context is shared across probes. 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 three sentences, each earning its place: purpose, method/usecase, and return value. It is front-loaded and wastes no words, 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 moderate complexity and absence of an output schema, the description is complete: it explains what it does, how it works (via ai_visibility_check), why to use it, and what it returns (ranked list with metrics). This provides enough context for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal parameter meaning beyond the schema: it reiterates that context is shared and notes first entity is the 'subject', but these are already in the schema. The description's mention of probing mechanics doesn't enhance 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 purpose with specific verbs ('Compare', 'Probes', 'ranks') and a well-defined resource: AI visibility across multiple entities. It distinguishes itself from sibling tool ai_visibility_check by focusing on side-by-side multi-entity comparison and ranking.

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

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

The description provides clear usage context: competitive AI-marketing audits with an example query. It implies it is the multi-entity alternative to ai_visibility_check by mentioning it probes each entity with that tool. However, it does not explicitly state when not to use this tool or name exclusion criteria, keeping it just short of a 5.

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

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

Annotations already declare read-only, idempotent, and open-world behavior. The description adds significant context beyond that: it fans out across two external services, returns a specific summary block, and explicitly explains partial failure handling and potential timeout (5-30s for bundlephobia's first measurement). This gives the agent a clear picture of what to expect, with no contradiction.

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

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

The description is dense but well-structured: it opens with the core purpose, then gives usage triggers, return fields, ecosystem scope, and failure behavior. Every sentence carries useful information with no fluff or repetition, making it concise despite its length.

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

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

Since there is no output schema, the description compensates by enumerating the summary block fields (is_latest, license, etc.) and other return elements like per-advisory detail and links. It also covers data sources, scope limitations, and partial failure modes. Given only 2 parameters and a complex composite behavior, the description is remarkably complete.

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

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

The input schema fully describes both parameters ('package' and 'version') with clear explanations, so schema coverage is 100%. The description does not add any additional parameter details beyond what the schema already provides, so 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 it's a 'Composite "should I add this npm package to my project" check in ONE call' and specifically names the data sources (deps.dev and bundlephobia). It defines the resource as an npm package and the primary purpose as evaluating safety, popularity, and size, making it distinct from sibling research tools.

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

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

The description gives explicit use cases: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also offers a clear when-not-to-use by stating 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'. However, it doesn't name a specific sibling tool as an alternative, only an external service.

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, but the description goes far beyond them. It discloses the embedding model (BGE-base-en), similarity mechanism (cosine), chunking strategy (500-char overlapping windows), the 200K character limit, and truncation behavior with a flag. It also reveals that results include character offsets and similarity scores, which are important behavioral traits not covered by annotations.

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

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

The description is rich but tightly organized. Each sentence contributes unique value: the core operation, the use case/benefit, the verification capability, the companion workflow, and technical constraints. It's front-loaded with the main action and avoids waffle.

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 still explains the return format (top-N passages with character offsets and similarity scores) and encompasses usage context, parameter semantics, technical capabilities, and limitations (200K cap/truncation). This is complete for an agent to decide when and how to call it.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaningful context: text is described as the fetched record with a max size, query gets concrete examples of natural-language phrasing, and limit is implied by 'top-N passages.' This goes beyond simply repeating 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 performs semantic search INSIDE a fetched record, with a specific verb+resource combination. It distinguishes from siblings by emphasizing it operates on text the user already has, not on external sources, and positions itself as a context-saving alternative to cramming whole documents into prompts.

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

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

The description explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also names a specific alternative/companion tool, ask_pipeworx_grounded, and explains the workflow of fetching with the gateway and grounding over relevant passages. This provides clear usage context and differentiates from 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?

Beyond the annotations (readOnlyHint=false, idempotentHint=true, etc.), the description discloses critical behavioral details: account requirements, delivery channel limitations (email/sms verification, 10/day cap), webhook signing secret returned exactly once, and auto-disabling after 10 consecutive failing runs. It also clarifies that the feed is always on and how to access it. This is rich contextual information that annotations alone do not provide.

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

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

The description is dense but well-structured: it starts with the main purpose, then covers account requirements, supported types with examples, and delivery channels with caveats. While it is longer than average, every sentence adds meaningful information about configuration options, constraints, or side effects. It is front-loaded with the core action and return 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 tool with multiple subscription types, nested objects (delivery), and important prerequisites, the description covers all essential aspects: auth requirements, type-specific params, delivery options (feed, email, sms, webhook), return value (subscription id), and behavioral caveats (verification, caps, auto-disable). No output schema exists, but the description explicitly mentions the returned subscription id, making the tool's behavior understandable enough for an agent.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds further value by giving concrete parameter examples for each subscription type (e.g., items:["5.02"] = officer change for sec_8k, min_spread_bps for polymarket_edge, series_id for fred_series). It also clarifies delivery object semantics (e.g., email sends templated alert, sms must match verified phone, webhook POSTs event JSON with HMAC signing). This goes beyond the schema's generic property descriptions.

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

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

The description opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly distinguishes the tool from siblings like list_subscriptions, unsubscribe, and recent_alerts, which handle viewing, removing, or reading alerts rather than creating subscriptions.

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

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

The description provides clear context for when to use the tool, including the prerequisite of a Pipeworx OAuth account and the note that anonymous/BYO cannot persist subscriptions. It also explains the always-on feed and how to pull alerts (via recent_alerts or a GET endpoint), which implicitly contrasts with the creation action. However, it does not explicitly name alternative tools for other actions (e.g., unsubscribe) or state 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 the tool as read-only, open-world, idempotent, and non-destructive, so the safety profile is covered. The description adds behavioral context by detailing the return format (category-bucketed example questions with exact tool+argument shape) and the effect of passing a topic (focuses the spread), which goes beyond the annotations.

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

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

The description is dense but well-organized, front-loading natural language queries to aid intent recognition and then clearly explaining the tool's output and usage. Every sentence provides useful information, though the initial list of example queries is somewhat redundant with the overall purpose and could have been shortened.

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 simple input (one optional parameter) and no output schema, the description fully explains what the tool returns (category-bucketed examples), how to invoke it, and when to use it within the broader context of sibling tools. It covers both the 'what' and the 'how', making it comprehensively documented.

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 covers 100% of parameter documentation with a detailed description of the `topic` parameter, including allowed values and omission behavior. The description adds minimal extra meaning beyond the schema by giving example topics ('finance', 'pharma', 'betting'), but these are already enumerated in the schema, so the description's contribution is marginal.

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

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

The description clearly identifies the tool as the onboarding entry point for Pipeworx, stating it returns category-bucketed example questions with exact tool+argument shapes. It uses a specific verb ('returns') and resource ('example questions'), and distinguishes itself from siblings by positioning it as the first tool to use when unsure what to ask.

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 context for when to use the tool ('Use this FIRST when you do not yet know what Pipeworx can do for you') and how to call it (no arguments for full spread, or pass `topic` to focus). It also mentions learning how to call meta-tools, giving clear usage guidance, though it does not explicitly exclude sibling tools like discover_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?

The description adds meaningful behavioral details beyond the annotations: the row is deactivated rather than deleted, and historical events remain accessible via recent_alerts. This clarifies the non-destructive nature explicitly (matching destructiveHint=false) and explains the post-condition in a way the annotations alone do not.

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 exactly two sentences, with the primary action front-loaded. The second sentence packs essential constraints and side effects into a compact, clear structure, and every phrase contributes to understanding the tool's behavior.

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 cancellation tool, this description is complete: it states the action, ownership requirements, and the non-destructive outcome. Since there is no output schema, the description carefully covers the tool's side effects and relationship to recent_alerts, giving an agent everything needed to invoke it correctly.

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

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

With only one parameter and 100% schema description coverage, the schema already fully documents the parameter ('Subscription id (uuid) returned by subscribe'). The description only repeats 'by id' without adding new semantic detail, so it stays at the baseline for good schema coverage.

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

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

The description opens with 'Cancel a subscription by id,' a specific verb+resource pairing that clearly identifies the tool's action and scope. It distinguishes itself from related tools like subscribe and list_subscriptions by focusing on cancellation, and it references recent_alerts to clarify the relationship between deactivation and historical data.

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

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

The description provides clear usage context by stating ownership is enforced—only the user's own subscriptions can be canceled—which is a critical constraint for invoking the tool. It doesn't explicitly name alternative tools or include 'when not to use' guidance, but the purpose is unambiguous enough to infer appropriate usage.

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

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

Annotations already provide readOnly/idempotent safety, but the description adds critical behavioral context: the two pipelines (financial vs. other claims), the meaning of each verdict, and a clearly emphasized warning that could_not_verify must not be treated as evidence. This goes far beyond the structured annotations and is essential for correct usage.

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 well-organized, front-loading purpose and then detailing pipelines, return values, and error semantics. Every sentence adds information, but it is longer than the two-sentence gold standard. It remains efficient for the complexity it covers, earning a high but not perfect score.

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

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

For a complex tool with no output schema, the description is remarkably complete. It explains the return value shape (verdict, actual value, citation, reasoning), the two execution paths, and the special handling of error/unsupported outcomes. An agent would know exactly what to expect and how to interpret results.

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

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

Schema coverage is 100%, so parameters are already well-documented. The description adds extra semantics by explaining that tolerance_pct overrides the implied tolerance and suggesting 1-2 for hallucination detection, which goes beyond the schema's 'Max percent deviation' description. This extra guidance earns a score above baseline.

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

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

The description clearly identifies the tool as a claim verifier with a specific verb ('verify') and resource ('claims'). It lists example user phrasings and explicitly states it returns a verdict, distinguishing it from general-purpose Q&A tools like ask_pipeworx or research tools like deep_research. The structured vs. grounded pipeline detail further differentiates its behavior.

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 explicitly to use when checking factual correctness and notes it replaces 4-6 sequential calls, giving clear when-to-use context. However, it does not name alternative tools or state when not to use it, so it falls short of a top score. The guidance is otherwise concrete and useful.

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