cocktails

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safe-read profile is known. The description adds valuable behavioral context: the default model (Workers AI Llama-3.3-70b, free), optional Anthropic probing with a BYO key and direct billing, and the return structure (per-model fields + combined view). This goes beyond the annotations and addresses key operational traits.

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

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

The description is three sentences: the first states the primary function and output, the second covers model options and cost implications, and the third lists return fields and use cases. Every sentence carries useful information with no redundancy. It is front-loaded and efficiently structured.

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

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

For a read-only probing tool with rich annotations and a 100% schema-coverage, the description is thorough. It explains the return format (per-model score, confidence, signals, raw_response + combined view) despite no output schema, and provides enough context on model choice and cost. It also gives practical use cases, making it complete for an agent to invoke correctly.

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

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

Schema description coverage is 100% for all four parameters, so the schema already explains them well. The description adds no new parameter-level meaning beyond referencing the default model and the `_apiKey` for Anthropic, which is also in the schema. Baseline 3 is appropriate because the description doesn't significantly enhance what the schema provides.

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

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

The description clearly states the tool probes one or more LLMs for what they know about a business/brand/product/topic and scores visibility (0-100) per model. This is a specific verb+resource+output combination. While there is a sibling 'scan_competitor_ai_presence' that could overlap, the description's focus on per-model visibility scoring and combined view distinguishes its core function.

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

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

The description provides clear use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' However, it does not explicitly mention when not to use this tool or alternative sibling tools, so it stops short of full exclusion guidance. The context is clear but no alternatives are 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 declare readOnlyHint=true and idempotentHint=true, and the description adds useful behavioral context: it mentions the tool fills arguments, returns structured answers with stable pipeworx:// citation URIs, and works on every tier with one fast call. The description does not contradict annotations, and while it doesn't disclose every edge case, it provides meaningful behavior 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?

Despite its length, every sentence serves a purpose: it lists supported data domains, explains the routing mechanism, provides concrete examples, and contrasts with sibling tools. The structure is front-loaded with the key 'PREFER OVER WEB SEARCH' directive and follows a logical progression, making it dense but not wasteful.

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

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

For a complex tool with no output schema, the description adequately covers what the tool returns (structured answer with citation URIs), what it can answer, and how to decide between this and related tools. It also notes 'works on every tier' and 'one fast call,' setting expectations for resource usage. The description is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, with the schema already documenting the 'question' parameter and its aliases (q, prompt, text, input, query). The description adds little to parameter semantics itself, instead focusing on tool-level behavior. Since schema_description_coverage is high, the baseline of 3 is appropriate; the description does not need to compensate.

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

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

The description explicitly states it routes questions to 5,366 tools across 1,396 verified sources and returns structured answers with citation URIs, using specific verbs like 'routes' and 'returns.' It clearly distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for different use cases, making the purpose unambiguous.

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

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

It provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' for factual questions, 'START HERE for most questions,' and even lists trigger phrases like 'what is,' 'look up,' and 'find.' It also gives clear when-not-to-use instructions by directing to ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad questions, making alternatives 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?

The annotations already declare read-only, idempotent, and non-destructive behavior. The description adds that this is a beta with candidate routing improvements enabled live when under test, and that no candidate is currently active (retired 2026-07-26), so behavior matches ask_pipeworx. This discloses the experimental and potentially changing nature, which goes beyond annotations.

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

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

The three-sentence description is front-loaded with the core purpose, followed by current status and usage guidance. Each sentence provides essential information with no redundancy, though the specific retirement date is arguably an extraneous detail that could become stale.

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 this is a complex router with no output schema, the description appropriately references the sibling ask_pipeworx for response shape, explains current parity, and confirms it is a full working router. It covers the key context an agent needs: what it is, when to use it, and its experimental nature, while delegating output details to the sibling.

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

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

All six parameters are aliases for the single question parameter, and the schema descriptions fully cover their meaning (100% coverage). The description does not add parameter-specific details beyond saying 'same arguments', so it relies on the schema entirely.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with 5,366 tools, same arguments and response shape. It distinguishes itself from the stable sibling by positioning as the experimental edge with candidate routing improvements. The purpose is explicit and differentiated.

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 instructs to use it exactly like ask_pipeworx when wanting the newest routing, and mentions that results are compared against the stable router. It clarifies the current state (no active candidate) and that it is a full working router, not a fallback, providing clear when-to-use 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 declare readOnly/openWorld/idempotent/non-destructive, but the description adds substantial behavioral detail: it extracts the answer EXCLUSIVELY from the tool result, returns a structured success object with evidence and confidence, and refuses with specific named reasons (not_in_source, no_tool_match, etc.). It also discloses the extra LLM call cost. 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 three sentences, but each sentence is information-dense and purposeful: the first establishes the core function and mechanism, the second specifies the return contract (success and refusal shapes), and the third gives usage guidance and cost trade-off. No filler words; the structure front-loads the most critical information.

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

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

There is no output schema, so the description must carry the full burden of explaining return values. It does so comprehensively, enumerating both success fields (answer, evidence, confidence, source, fetched_at) and explicit refusal reasons. It also covers operational context (cost, routing, when to use) and failure modes, making the description complete for a tool of this complexity.

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

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

The schema covers all 6 parameters with 100% description coverage—each is explicitly an alias for 'question' and the principal 'question' parameter is fully described. The tool description does not add parameter-specific semantics beyond the schema, so a baseline score of 3 is appropriate. The description's focus on output/behavior is more valuable here.

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 and precise purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly explains the mechanism (routes through tools, extracts answer only from result) and distinguishes itself from sibling ask_pipeworx by name and by contrasting the hallucination-resistant extraction behavior. This is a specific verb+resource+scope characterization.

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

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

Usage conditions are explicit: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples (financial verdicts, legal claims, medical lookups). The description also names the alternative ask_pipeworx and states the cost trade-off ('Costs one extra LLM call'), advising to prefer it for casual lookups. This is textbook when-to-use and when-not-to-use guidance.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses extensive behavioral detail: fan-out to category-specific data packs, resolver contract with match confidence fields, low-confidence short-circuit status, closed-market status, wide-spread market warnings, cancellation-rule parsing, and news fallback behavior. This is far beyond what annotations provide.

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

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

The description is long but highly structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every sentence carries specific, actionable information for a complex tool. Front-loaded with purpose and usage, followed by necessary details in a readable format.

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

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

Given the tool's complexity (3 params, multiple classifiers, fan-out logic, response shapes), the description is remarkably complete. It covers return value shapes even without an output schema, addresses failure modes (GDELT 429, closed markets), safety guards, and resolution-rule risks. No gaps are apparent.

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

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

Even though schema coverage is 100%, the description enriches each parameter substantially. It gives concrete examples for 'market' (slug, URL, question text), explains 'depth' with quick vs thorough outcomes, and clarifies 'include_raw' with response size implications and when to set true. This adds meaning beyond the schema's descriptions.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from siblings like polymarket_arbitrage or polymarket_edges by focusing on a single bet with evidence fan-out. The tool's scope (resolving, classifying, returning evidence) is explicit.

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

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

The description explicitly states 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' – clear usage contexts. However, it does not explicitly mention when NOT to use this tool or name alternative sibling tools for other scenarios, so it stops short of full when-not/alternatives guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds context by stating it returns only cocktail id, name, and thumbnail, and that it lists 'all' cocktails, which clarifies scope beyond the annotations. No contradiction is present.

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

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

Two concise sentences: first states the primary action and examples, second clarifies return fields and points to an alternative. No wasted words, information is front-loaded and directly useful.

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

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

The tool is simple (one parameter, no nested objects) and has an output schema. The description covers the essential behavior and return scope, while the output schema handles return values. The alternative for full recipes is also mentioned, making it fully 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 coverage is 100% with a clear description of the 'ingredient' parameter. The description provides examples (e.g., 'vodka', 'lime juice') but does not add meaning beyond the schema, which already explains the parameter. Baseline 3 is appropriate.

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

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

The description clearly states the tool lists all TheCocktailDB cocktails containing a specific ingredient, with a specific verb and resource. It also distinguishes itself from the sibling get_cocktail by noting it returns only id, name, and thumbnail, making the purpose unambiguous.

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

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

The description explicitly tells the agent when to use this tool (to list cocktails by ingredient) and when to use an alternative ('use get_cocktail to retrieve full recipes'). This provides clear guidance on selecting between related 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 readOnly/openWorld/idempotent/non-destructive annotations, the description discloses what data is fetched (latest 10-K revenue, net income, cash, long-term debt; FAERS adverse-event counts, FDA approval counts, active trial counts), mentions correct handling of off-calendar fiscal years, and states the results are sorted by primary metric with citation URIs. This is rich behavioral context that 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 dense but well-organized: it opens with trigger phrases, then states the core action and preference rule, then details each type's data pull, sorting, and output. A few clauses (e.g., specific fiscal-year examples) add valuable context, though the length is somewhat high. Overall each sentence earns its place.

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

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

Given there is no output schema, the description adequately explains return behavior: paired data, pipeworx:// citation URIs per entity, and sorted results. It also covers scope (2–5 entities), data sources per type, and the replacement of 8–15 sequential lookups, making the tool self-explanatory for an AI agent even in the context of sibling tools.

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

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

The input schema already covers both parameters fully with enum and array constraints. The description adds semantic value by explaining what each 'type' pulls (company vs drug) and providing concrete examples for values (e.g., ['AAPL','MSFT']). It does not repeat schema mechanics but enriches meaning with data-source specifics.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in a single parallel call, and specifies the data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/trials for drugs). It distinguishes itself from sequential lookups and siblings by explicitly saying to prefer it over multiple single-entity calls.

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 trigger phrases ('Compare X and Y', 'X vs Y', 'which is bigger/better/larger/more profitable', 'rank these companies') and explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also clarifies the entity count range (2–5) and the data types pulled for each entity type, making usage conditions clear.

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

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

Annotations already mark it read-only, idempotent, and non-destructive, but the description adds substantial behavioral context: account requirements, paid tier, decomposition strategy, output structure (gaps[], contradictions[], hop field), semantic excerpting, and latency expectations. 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 dense, with most sentences adding unique information. However, the depth-level explanation somewhat repeats the input schema's description, and the overall length could be trimmed slightly without losing 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?

With no output schema, the description compensates by detailing the findings packet: verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], and hop field. It also covers latency, excerpting behavior, and fallback alternatives, making it a complete guide 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 already documents both parameters with 100% coverage, but the description enriches them by explaining how depth levels behave ('quick=3 single hop', 'standard=5 adds gap-recovery', 'thorough=8 paid') and by noting questions should be broad/multi-part. This goes well beyond the enum names.

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 grounded multi-source research across Pipeworx's 1396 structured data sources, decomposing questions into facets and routing them to parallel tools. It explicitly contrasts with ask_pipeworx, distinguishing it 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: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx'. Also warns against breaking news topics and directs to ask_pipeworx's live news APIs.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds meaningful behavioral context: it returns top-N most relevant tools with names, descriptions, and full input schemas (with curated examples), and states results are ready to call directly with no second schema lookup needed. This discloses return format and workflow implications beyond annotations.

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

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

The description is structured with clear sections: purpose, when to use, return behavior, and a strong directive to call first. The list of domains is long but informative and earns its place. Slightly wordy but each sentence contributes valuable 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?

For a discovery tool with no output schema, the description is highly complete. It explains the return format (top-N tools with full schemas), the direct-call capability, the aliases and parameter flexibility via schema, and the intended usage as a first step. No critical information is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'describing the data or task' which aligns with the query parameter, but adds no detail beyond the schema. The limit parameter is not discussed in the description, though it is covered in the schema. The description provides no extra semantic value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses a specific verb (find) and resource (tools), and differentiates from siblings by positioning this as a meta-search tool for discovering other tools. The scope is explicit with examples of domains (SEC filings, FDA drugs, etc.).

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

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

The description provides explicit usage guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' This clearly tells the agent when to invoke this tool relative to 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 the tool read-only, idempotent, and non-destructive. The description goes far beyond this by disclosing the internal parallel fan-out across SEC EDGAR, XBRL, USPTO, GDELT/GNews, and GLEIF; the exact returned fields (cik, recent_filings, fundamentals, patents, news, LEI); sorting behavior for fundamentals; and the patent API soft-fail. This is rich behavioral context 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 long but information-dense. It opens with user-phrased examples (good for LLM matching), then defines core behavior and return fields. Every sentence contributes key detail (sources, counts, sorting, fallbacks, constraints). It could be slightly trimmed, but the length is justified by the tool's multi-source complexity and the need to convey fallback 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?

Given there is no output schema, the description is remarkably complete: it enumerates every returned field group, the maximum number of filings, URI format, date sorting, source fallback for news, and the explicit name limitation with a workaround. Combined with the four strong annotations, the agent has everything needed to decide and use this 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?

Input schema documents both parameters and even includes examples and the name restriction. The description adds value by giving concrete examples ('AAPL', '0000320193'), emphasizing the zero-padded CIK requirement, and explicitly stating the unsupported name input. It reinforces the resolve_entity workaround, which is not in the schema. Since schema coverage is 100%, the baseline is 3; the additional examples and exclusions earn a 4.

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

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

The description clearly defines the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call' with multiple example queries. It distinguishes itself from siblings like compare_entities and resolve_entity by explicitly targeting holistic company profiling and by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news 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 explicit when-to-use guidance: 'when the user asks for a holistic view.' It also names the alternative (use resolve_entity for names), and gives a critical exclusion: 'names not supported.' It additionally flags the USPTO patent API sunset and soft-fail behavior, which is valuable for managing expectations.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the destructive nature is known. The description adds minimal behavioral context beyond purpose, such as the target ('previously stored memory') and use cases (clearing sensitive data), but does not explain what happens when a key is absent or if deletion is permanent. With annotations covering the safety profile, this is adequate but not rich.

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

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

The description is two sentences, front-loaded with the action ('Delete a previously stored memory by key'), followed by clear usage scenarios and companion tools. There is no waste; every sentence contributes value.

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

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

Given the tool's simplicity (1 parameter, no output schema) and the presence of annotations (destructive, idempotent), the description covers purpose, usage criteria, and related tools. It does not detail return behavior, but for a simple delete operation this is not critical. The inclusion of 'sensitive data' as a use case adds useful context.

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

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

The input schema covers 100% of the parameter with 'Memory key to delete.' The description's 'by key' adds no extra meaning beyond what the schema already provides. Since schema coverage is high, the baseline of 3 applies.

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

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

The description clearly states 'Delete a previously stored memory by key.' This uses a specific verb (Delete), a specific resource (memory), and the parameter (key). It also distinguishes from siblings by explicitly mentioning 'Pair with remember and recall,' making it the delete counterpart.

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

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

The description provides explicit usage contexts: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names related tools 'remember' and 'recall' as companions, giving clear guidance on when to use this tool versus alternatives.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable context: it fetches the page, extracts specific elements, and emits a single text blob. This goes beyond the annotations by explaining the underlying process and expected output.

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 efficiently structured: it leads with the purpose, then the process, output, and use cases. Every sentence adds value, and it's not overly verbose. It's well-organized and easy to scan.

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 (web fetch, external URL, no output schema), the description covers the essentials: what it does, how it works, and the output form. It lacks explicit mention of error conditions or network limitations, but for an external fetch tool with good annotations, this is adequate.

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 parameters 'url' and 'max_links' are already well-documented. The description doesn't add any additional parameter-specific semantics beyond what the schema provides, so it meets the baseline for high coverage.

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

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

The description clearly states the tool's function: generating a production-ready llms.txt file for any URL. It specifies the process (fetch page, extract title/description/key links), the output format (standard llms.txt markdown), and distinguishes itself from sibling tools by focusing specifically on llms.txt generation.

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

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

It provides concrete use cases: getting a client's site indexed, drafting your own project, and auditing a competitor. It doesn't explicitly name alternative sibling tools or state when not to use it, but the scenarios are 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the exact content of the returned recipe, which goes beyond the structured fields.

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, information-dense sentence with zero wasted words. It front-loads the core purpose and lists specifics concisely.

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 a single parameter, clear annotations, and an output schema present, the description covers the essential context. It states what the tool returns and implies when to use it, making it fully adequate for selecting and invoking.

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

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

The schema has 100% coverage for the single 'id' parameter, so the baseline is 3. The description adds only 'by ID' which repeats the schema, providing no additional semantic meaning.

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

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

The description clearly states the verb 'Get' and the resource 'full cocktail recipe by ID', specifying return content (ingredients, measurements, steps, glassware, garnish). This distinguishes it from siblings like random_cocktail or cocktails_by_ingredient.

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 the tool is used when you have a cocktail ID, providing clear context. It does not explicitly name alternatives, but the 'by ID' scope makes it obvious when to use it versus search or random.

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 the safety profile is covered. The description adds context by listing the exact returned fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying the 'caller's active subscriptions' scope, which goes beyond the schema.

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

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

The description is two sentences, front-loaded with the action and return fields, then provides practical usage guidance. Every sentence earns its place with no redundancy or filler.

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

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

With no output schema, the description fully compensates by enumerating the return fields. It also covers the primary use cases (review before adding, find id to cancel) and relies on annotations for safety semantics, making it complete for a simple list 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% for the single optional parameter include_inactive, whose description already explains it includes cancelled subscriptions with default false. The tool description adds little beyond what the schema provides, so the baseline of 3 applies.

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

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

The description uses a specific verb ('List') and resource ('the caller's active subscriptions'), clearly distinguishing this from sibling tools like subscribe and unsubscribe. It also specifies the scope (caller-specific, active only) and references the return fields.

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: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implicitly distinguishes it from subscribe/unsubscribe and recent_alerts, though it does not explicitly name 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 are all false, providing no safety/hint signals. The description compensates by disclosing operational behavior: rate-limited to 5 per identifier per day, free (doesn't count against quota), team reads digests daily, and feedback affects roadmap. This gives the agent a clear understanding of side effects and limitations 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?

Four sentences, each earning its place: purpose, use-case triggers, content guidance, and operational constraints. Front-loaded with the core action, 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?

The description fully covers the tool's purpose, usage scenarios, content rules, and constraints. Given the simple 3-parameter schema and absence of an output schema, it provides all necessary context for an agent to invoke the tool correctly. It even clarifies the optional context object's intent through description.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds value by mapping real-world triggers to enum values: 'wrong/stale data' → bug, 'wish existed' → feature/data_gap, 'worked surprisingly well' → praise. This contextual mapping helps the agent choose the correct type, going slightly beyond what the schema alone provides.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates the feedback categories (bug, feature/data_gap, praise) and distinguishes this tool from any sibling tool by focusing on team communication rather than research or data 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?

Explicitly states when to use: '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 provides a when-not instruction: 'don't paste the end-user's prompt,' which adds content-level guidance. No alternative tool is needed since none of the siblings serve a feedback role.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description adds valuable behavioral context: it discloses the data source ('derived from CF analytics-engine'), privacy guarantees ('no PII, just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). This informs the agent about potential staleness and the aggregated nature of the data, going beyond the schema and annotations.

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

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

The description is concise and front-loaded: it opens with a clear hook, then lists the return values and use cases, and ends with technical details. Every sentence serves a purpose—introducing the concept, listing applicable scenarios, and providing data provenance/caching info. It avoids redundancy and is well-structured for quick scanning.

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

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

For a read-only aggregation tool with a single optional parameter and no output schema, the description is sufficiently complete. It covers what is returned (top tools, packs, volume), the selected window, and important caveats (caching, no PII). The absence of an output schema is mitigated by the clear description of the returned aggregate data. Combined with the strong annotations, the agent has everything needed to invoke and interpret 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?

The single parameter 'window' is fully described in the schema with its enum values and meaning, so the description adds no extra semantics beyond what the schema already provides. The description merely mentions 'a recent window (24h, 7d, or 30d)' without elaborating on trade-offs, which the schema already does. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb ('Returns') and resource ('top tools, top packs, and total call volume over a recent window'). It distinguishes itself from sibling tools by framing it as a self-aggregating signal derived from other AI agents' calls, which is unique among the listed siblings. The three use cases further clarify its niche (discovering hot data sources, confirming canonical choices, and aligning with agent needs).

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

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

The description provides explicit use cases, such as discovering hot data sources for current events and confirming a popular tool before asking questions. However, it does not explicitly state when NOT to use this tool or name alternative tools, so it falls short of a full 5. The context is clear enough for an agent to decide when this tool is appropriate.

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

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

Beyond the annotations (readOnlyHint, openWorldHint), the description discloses detailed behavioral traits: the >3pp threshold for signals, placeholder fraction >20% returning null, semantic similarity ≥0.30 Jaccard, and fill check pricing against live CLOB depth with 'realizable_edge_pp ≤ 0 means... do not trade it.' 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?

Well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. Every sentence carries essential technical information without filler, despite being long.

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

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

Given the tool's complexity (two optional modes, no output schema), the description covers everything: invocation patterns, response structure (opportunities[], partition_check), failure conditions (low similarity, placeholder fraction), and a pointer to polymarket_fill_risk. It is sufficiently complete 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% and descriptions already explain event and topic. The tool description adds significant behavioral semantics: event mode 'walks child markets, checks date-axis / threshold-axis ordering AND computes the partition_check', topic mode 'searches related events... flattens markets, runs the comparator on the union', and NO args for trending_scan.

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?

Opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the three modes (no args, event, topic) and differentiates from sibling tools like polymarket_edge_tracker and polymarket_fill_risk.

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

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

Provides explicit use guidance: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', 'topic for a themed cross-event scan'. Recommends event for a specific market and topic for cross-event scanning, and even points to polymarket_fill_risk for custom sizing.

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 adds substantial behavioral disclosure beyond annotations: three response segments, model families, per-leg logic, diagnostics, caching at KV level, and 24h-move warnings. Annotations only declare read-only/idempotent, so the description carries the burden and exceeds it.

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

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

Very long and dense, with structured sections but heavy jargon. While the complexity justifies length, there are redundant explanations and some sentences could be tighter. Front-loaded purpose and organized structure, but not 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?

No output schema, so description must explain response structure: by_segment, fed_candidates, _diagnostics. It covers edge cases, placeholder filters, empty-segment reasoning, and caching behavior. Extremely complete for a complex 9-parameter 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 covers 100% of parameters, so baseline is 3. Description adds cross-parameter semantics: explains why min_kelly doesn't filter partition arbs, how min_partition_leg_kelly applies per-leg, and how slippage_pp is netted from edge. This goes beyond the schema's individual parameter descriptions.

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

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

Specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' Clearly distinguishes from siblings by focusing on discovery for 'what should I bet on today' without paging hundreds of markets.

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

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

Provides clear context with the intended use case and explains the tradeable-edge knobs and diagnostics. Mentions exclusions like Fed bets being unreliable and concentrated_longshot being rare-by-design. Does not explicitly enumerate alternatives (e.g., when to use polymarket_arbitrage instead), so not a 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?

The description goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It reveals snapshot write behavior (cache-miss), 60-day TTL limits, decay computed on daily closes not intraday, signed edge_pp_net meaning, and gap interpretation. This is rich, non-obvious behavioral context that annotations alone cannot convey.

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

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

The description is well-structured with clear sections: purpose statement, arguments, RESPONSE, and LIMITS. It front-loads the core question and uses caps labels for readability. However, it is somewhat long and includes some details that could be seen as verbose, though most sentences earn their place by explaining non-obvious 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?

With no output schema and a complex response structure (tracked[], expired[], snapshot_dates[]), the description fully explains every field, the meaning of trends and decay metrics, and important limits like TTL and gap handling. The behavioral caveats (daily closes vs intraday) and snapshot write conditions make this complete for an agent to invoke and interpret results correctly.

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

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

The input schema already describes both parameters fully (100% coverage), including defaults and valid values. The description mostly restates these defaults ("days (lookback, default 14, max 30)", "window (snapshot family, default '1wk')") with minimal added context. It adds the 'snapshot family' framing but does not substantially enrich parameter understanding beyond the schema.

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

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

The description opens with a specific verb+resource: "Edge persistence and decay telemetry built from daily polymarket_edges snapshots." It immediately answers a concrete question ("how long has this edge existed and is it shrinking?") and differentiates from siblings by focusing on time-series persistence rather than point-in-time edge values.

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

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

The description gives clear context on when this tool is valuable (e.g., "a fresh wide edge and a 3-week-old wide edge are different trades") and explains the response semantics for expired opportunities. However, it does not explicitly name sibling alternatives like polymarket_edges or when to choose one over the other, so it lacks direct exclusionary guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is known. The description goes far beyond annotations by detailing what the tool does internally ('walks the ladder'), what it returns (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict), and the key risk (partial basket fills convert an arb into an unhedged directional position). This is rich behavioral context, especially valuable since there is 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 dense and front-loaded with purpose, then mode-specific details. Every section earns its place (mode requirements, behavior, return values, risk warning, usage threshold). However, it is a long paragraph (~250 words) and includes some motivational prose ('the dominant loss mode in real arb-bot P&L') that could be trimmed. Structurally it's organized but not maximally 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?

Given the complexity (two modes, four parameters, no output schema), the description is remarkably complete. It explains both modes, all parameter semantics, defaults, return fields, risk warnings, and the exact conditions under which to use the tool relative to its siblings. No critical information appears missing.

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

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

Schema coverage is 100%, but the description adds crucial semantics: side defaults and meaning in each mode, size_usd interpretation ('max spend on buys, target proceeds on sells' vs 'settlement notional S'), and the requirement to provide exactly one of market or event. It also clarifies that size_usd is clamped (though this already appears in the schema). The description substantially enhances the schema information.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools by naming polymarket_arbitrage and polymarket_edges and stating it should be used before acting on their signals. The two modes (single-market and basket) are explicitly scoped, making the tool's 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 when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also gives mode-specific instructions (when to pass market vs event, default side behavior), and explains why it's necessary (theoretical overround on thin books is not capturable, partial fills create unhedged positions). This is exemplary usage guidance.

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

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

The description richly discloses behavioral details beyond the annotations: it explains what compatibility_warning means in two distinct cases, how temporal_alignment affects spread validity, and what skipped_cross_type/subtype counters represent. It also clarifies the output structure (leg-by-leg prices, top_spreads_pp). No contradiction with the readOnlyHint/idempotentHint annotations; it is a safe read/comparison tool.

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

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

The description is lengthy but well-structured with clear section labels (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds unique value, but the density might be overwhelming at first glance. Still, the front-loaded purpose sentence and logical organization earn a 4.

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 fully covers the return format, safety field semantics, and the meaning of alignment flags. It addresses edge cases (non-equivalent bet shapes, unrelated events) and warns about real-world limitations. The description is complete for a complex cross-venue comparison tool with 0 required 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?

Although the schema has 100% coverage of the three parameters, the description adds crucial behavioral meaning: it lists the 10 pre-mapped topic shortcuts, explains how topic auto-fetches matching events, and states that explicit kalshi_event_ticker/polymarket_event_slug override the mapped sides. This transforms the parameters from simple strings into a clear selection mechanism.

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

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

The description opens with a clear, specific statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from sibling tools by explicitly focusing on the Kalshi–Polymarket comparison, not just general Polymarket arbitrage or edges. The two-mode (topic vs explicit ticker/slug) structure further clarifies what the tool does.

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

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

The description provides explicit guidance on when to use the tool and how to interpret results. It details both modes, explains compatibility_warning scenarios, and cautions that 'pre-mapped ≠ tradeable' and that most pre-mapped topics return warnings. This goes beyond simple alternatives and gives the agent actionable decision rules for using the tool correctly.

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, non-destructive, and idempotent, reducing the description's burden. The description adds a brief note about return structure, but it does not disclose any additional behavioral traits (e.g., randomness not being reproducible, absence of filtering). This is adequate but not rich.

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

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

The description is a single, front-loaded sentence with no filler. It immediately states the action and then lists the key output details, earning every word.

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 simplicity (no params), rich annotations, and presence of an output schema, the description covers the essentials. It could mention how randomness works or explicitly contrast with get_cocktail, but it is largely complete for this low-complexity tool.

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

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

The tool has zero parameters, so the description is not burdened with explaining inputs. Baseline for 0 params is 4, and the description appropriately focuses on the return value.

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

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

The description clearly states the action ('Get') and resource ('random cocktail recipe'), and explicitly lists the return contents (ingredients, measurements, instructions, glassware, garnish). The word 'random' distinguishes it from sibling tools like search_cocktails and get_cocktail, which imply specific 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 no guidance on when to use this tool versus the many cocktail-related siblings (e.g., get_cocktail, search_cocktails, cocktails_by_ingredient). No explicit or implicit hints about when 'random' is preferred over a targeted search.

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. The description adds meaningful context beyond that: scoping to identifier (anonymous IP, BYO key hash, or account ID) and the listing behavior when key is omitted. 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?

Three sentences, front-loaded with the core action. Every sentence earns its place: the first defines the operation, the second gives usage context and examples, the third explains scoping and sibling pairing. 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 tool with a single optional parameter and no output schema, the description covers all essential aspects: action, usage, scoping, and relationship to siblings. The agent has enough information to select and invoke this 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%, but the description enriches the parameter semantics by explaining what values might be stored (e.g., target ticker, address, research notes) and explicitly noting the omit-to-list-all behavior, which complements the schema's parameter 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?

Description clearly states the tool's action: 'Retrieve a value previously saved via remember, or list all saved keys'. It names the relevant resource (memory) and explicitly distinguishes from sibling tools by referencing 'remember' and 'forget'. This exceeds a basic purpose statement by including the two distinct modes.

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

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

Provides explicit when-to-use guidance: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also names alternatives ('Pair with remember to save, forget to delete'), giving both context and exclusions.

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

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

The annotations state readOnlyHint=true and idempotentHint=true, implying the tool is a pure read with no side effects. The description explicitly says 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which is a persistent state change and breaks idempotency under repeated calls with mark_read=true. This directly contradicts the annotations, scoring 1 per the rubric.

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, unfiltered and front-loaded with the main purpose. Every sentence earns its place—purpose, return format/fields, filtering, mark_read semantics, polling note, and alternative access URL. No filler or repetition.

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

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

Given there is no output schema, the description appropriately details what each returned event contains ('source, citation_uri, and raw event payload'), covers all key parameters with examples, and even mentions the alternative HTTP endpoint. It is sufficiently complete for an agent to invoke confidently.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by giving a concrete type example ('sec_8k'), clarifying the 'since' parameter with 'ISO timestamp', and explaining the semantic effect of mark_read on subsequent calls. This elevates it above baseline.

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

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

The description opens with 'Pull fired events from your subscription feed,' which is a specific verb+resource pairing. It clearly distinguishes this from sibling tools like list_subscriptions (managing subscriptions) and recent_changes (tracking changes) by focusing on fired alerts from the persisted feed.

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 practical usage context: filtering by type/since, the mark_read behavior, and explicitly states 'Polls work fine.' It also provides an alternative URL for external scripts, suggesting appropriate contexts. However, it does not explicitly compare against sibling tools or state when to avoid this tool, so it stops short of a 5.

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

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

Despite annotations already declaring readOnlyHint, idempotentHint, and non-destructive behavior, the description adds operational depth: SEC EDGAR and USPTO sources, GDELT→GNews fallback on rate-limit/5xx, PatentsView API sunset with soft-fail, `since` format handling, and return structure. This goes well beyond what annotations alone convey.

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

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

The description is dense and well-structured: user intents → purpose → source fan-out → date format → return structure → alternative. Each sentence carries value, but the quoted example intents are somewhat repetitive and could be trimmed. Still, it is front-loaded and scannable.

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

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

With no output schema, the description takes on the burden of explaining return values, and it does: 'Returns structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' It also covers edge cases like source fallback and soft-fail for patents, plus the alternative tool. Given the multi-source complexity, this is 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% (context signals), with each parameter well-described (type enum, since formats, value examples). The tool description largely restates the `since` format and value examples already in the schema, adding no new per-parameter meaning. Baseline 3 is appropriate.

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

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

The description clearly states the tool is a change feed for a company, aggregating SEC filings, news (GDELT/GNews), and patents. It includes example user intents ('What's new with X', 'latest on Y') and explicitly distinguishes it from entity_profile, which is recommended for static profiles. The verb 'fans out' and the source enumeration make 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?

It explicitly provides when-to-use guidance through example query phrases and describes the tool as the right choice for 'change feed for a company in the last N days/weeks/months.' It also names a concrete alternative: 'Use entity_profile instead when you want the static profile...', which satisfies the 'when-not' criterion.

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

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

The description adds valuable behavioral context beyond annotations: persistence and scoping ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours', 'scoped by your identifier'). The idempotentHint and destructiveHint annotations are not contradicted by the description, and the description further clarifies the write 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?

Four concise, front-loaded sentences each with a distinct purpose: verb+resource, usage scenarios, storage/persistence details, and pairing with related tools. 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?

For a simple two-parameter tool with no output schema, the description covers the tool's purpose, when to use it, storage behavior, and related tools. It doesn't discuss overwrite behavior, but that is not essential given the simplicity and the idempotentHint annotation.

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 both parameters with 100% coverage, so the baseline is 3. The description provides example values ('a resolved ticker, a target address...') that align with the schema, but does not add significant new parameter semantics beyond what the schema already states.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It uses a specific verb ('save') and resource ('data'), and distinguishes from siblings by explicitly naming recall and forget as complementary tools ('Pair with recall to retrieve later, forget to delete').

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

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

Provides explicit usage guidance: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject)'. It also tells when not to use it by pointing to alternatives: 'Pair with recall to retrieve later, forget to delete'.

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 read-only/idempotent/non-destructive annotations by detailing exactly what each entity type returns (ticker, 10-digit CIK, company_name for company; RxCUI, ingredient, brand for drug), the upstream sources (SEC EDGAR, RxNorm), and even the citation URI format. It also discloses that each call cascades through multiple lookup endpoints, which is a nontrivial 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 well-organized: example queries first, then a clear usage directive, followed by detailed but compact per-type breakdowns. Each sentence contributes useful information, and the structure aids quick scanning. It is slightly verbose, but nothing feels superfluous for the complexity it covers.

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?

In the absence of an output schema, the description successfully explains return values for both entity types, including exact fields and sources. It also covers input formats and auto-disambiguation. It does not discuss error cases or edge conditions, but for a focused resolution tool, the provided context is sufficient for reliable use.

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

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

The schema already documents both parameters with useful descriptions and examples, providing 100% coverage. The description adds further semantic value by explaining what each type value actually returns (e.g., 'company' yields ticker+CIK+company_name) and by noting the flexibility of the value parameter (ticker, CIK, or name; brand or generic). This exceeds the schema baseline.

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

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

The description opens with concrete example queries ('What's the ticker for…' / 'find the CIK for…') and clearly states the tool resolves a user-spoken NAME to the canonical/official identifier. It explicitly enumerates supported types (company, drug) with their respective output fields, distinguishing it from sibling tools like entity_profile or compare_entities.

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

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

The description provides an explicit directive: 'Use FIRST whenever you have a name but need an ID.' It also mentions that it replaces 2-3 manual lookups, giving a strong usage trigger. However, it does not explicitly state when not to use the tool or name alternative tools for related entity tasks, so it falls short of a 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?

The description reveals meaningful behavioral details beyond annotations: it 'Probes each entity with ai_visibility_check', 'ranks by score', and returns a 'ranked list with score, confidence, signal density per entity'. This adds process and output context, while the annotations (`readOnlyHint`, `idempotentHint`) already cover safety. No contradiction detected.

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

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

The description is two sentences long, front-loading the core action ('Compare AI visibility across multiple entities side-by-side') and then adding a concrete use-case quote and output summary. Every sentence earns its place with 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?

Given the tool has no output schema, the description compensates by specifying return fields (score, confidence, signal density) and describing the ranking behavior. It also covers the primary use case and relies on the 100% schema coverage for parameter details. Minor gaps like model-specific behavior or rate limits remain, but they are secondary.

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 100% schema description coverage, the schema fully documents all four parameters. The description aligns with param semantics (e.g., 'your brand + N competitors' echoes the `entities` field) but adds no new parameter-level meaning beyond what the schema already provides, so the baseline score 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 opens with 'Compare AI visibility across multiple entities side-by-side', a specific verb+resource+scope that clearly indicates the tool's function. It further distinguishes itself from siblings like `ai_visibility_check` (single entity) and `compare_entities` (generic) by mentioning the side-by-side ranking and competitive audit use case.

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

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

The description provides clear context for when to use the tool: 'Useful for competitive AI-marketing audits' and clarifies it compares 'your brand + N competitors'. However, it does not explicitly state alternatives or exclusions (e.g., 'for a single entity, use ai_visibility_check'), so it falls short of fully explicit usage guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, sources_failed will list it if it times out, and the rest still returns. This is rich transparency.

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

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

The description is longer than typical but every sentence earns its place: purpose, usage, return structure, ecosystem limitation, and failure behavior. It front-loads the core purpose and uses structured clauses without wasted words.

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

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

There is no output schema, so the description compensates by enumerating return fields (summary block, per-advisory detail, links, alternative versions), ecosystem scope, and edge-case behavior (timeouts, partial failures). It is complete for a composite tool of this complexity.

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

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

Schema description coverage is 100%; the package parameter already mentions scoped packages, and version already mentions defaults. The description does not add further parameter-specific semantics, so baseline 3 is appropriate.

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

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

The description clearly states a specific purpose: a composite 'should I add this npm package to my project' check that fans out across deps.dev and bundlephobia. This verb+resource definition distinguishes it from sibling tools like scan_competitor_ai_presence and generic research tools.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives an exclusion/alternative for non-NPM ecosystems: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destructive action, so the safety profile is covered. The description adds meaningful context: it returns a limited set of fields and explicitly excludes preparation instructions, which is a behavioral constraint an agent would need to know. No contradiction with annotations.

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

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

Two concise sentences, front-loaded with the primary purpose. The first sentence states the action, the second gives return fields and a key limitation with an alternative. No wasted words.

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

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

For a simple one-parameter search tool with a rich output schema and annotations, the description covers the purpose, return fields, an important exclusion (prep instructions), and names the alternative. It is complete enough for an agent to decide when and how to use it.

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

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

The input schema fully covers the parameter with a clear description ('Cocktail name or partial name to search for'), so the description doesn't need to add much. The tool description merely echoes 'by name' without adding extra detail, giving baseline value.

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

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

The description clearly states the tool searches TheCocktailDB by name, which is a specific verb+resource combination. It distinguishes from siblings by noting the lack of preparation instructions and directing to get_cocktail for those, and the phrase 'by name' implicitly contrasts with cocktails_by_ingredient.

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

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

It explicitly states when not to use this tool ('no preparation instructions') and names the alternative (get_cocktail). The 'by name' scope also implies it's for name-based searches, not ingredient-based ones, providing clear guidance for selecting among 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?

The description goes beyond the annotations by disclosing the underlying embedding model (BGE-base-en), the windowing strategy (500-char overlapping windows), and the input cap with truncation behavior (200K chars, longer inputs truncated and flagged). It also reveals that output includes character offsets and similarity scores, which aligns with the readOnly and idempotent annotations without contradiction.

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

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

The description is three sentences and front-loaded with a clear definition and example use cases. Every sentence earns its place: the first defines the tool, the second explains when to use it, and the third provides technical constraints. 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?

Despite no output schema, the description explains the return value (top-N passages with offsets and similarity scores). It covers input requirements, operational behavior, limitations (truncation), and integration with a sibling tool, making it fully sufficient for a moderately complex search tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds minor value by framing 'text' as a fetched record and providing query examples, but the schema already defines each parameter. The description does not materially improve parameter understanding beyond what the schema offers.

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

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

The description clearly states a specific action ('Semantic search INSIDE a fetched record') with an identifiable resource (text already pulled from a source like a SEC 10-K). It distinguishes itself from siblings by emphasizing context-saving and by explicitly pairing with ask_pipeworx_grounded, making the tool's unique role obvious.

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

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

The description provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt.' It also names an alternative/complement (ask_pipeworx_grounded) and describes a workflow ('fetch with the gateway, ground over the relevant passages instead of the whole document'), giving clear context for selection.

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

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

Beyond the annotations, the description discloses several important behavioral traits: OAuth account requirement, inability for anonymous/BYO to persist subscriptions, phone verification for SMS, and the 10/day SMS cap. These add valuable context for side effects and prerequisites, with no contradiction to 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-structured, starting with the core purpose, followed by supported types and delivery options. Each sentence carries meaningful information, though the length is slightly high due to multiple examples and caveats.

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 (multiple subscription types, delivery channels, auth requirements), the description is thorough: it covers prerequisites, return value, supported types, delivery behavior, and limitations. The absence of an output schema is acceptable because the description mentions the return id, and the schema already handles param details.

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

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

The input schema already provides comprehensive descriptions for all parameters, including type-specific filters and delivery sub-fields. The description adds a few clarifying examples (e.g., items:["5.02"] = officer change) but largely repeats what the schema states, so the incremental value is modest.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. It distinguishes itself from siblings like list_subscriptions and unsubscribe by explicitly describing the creation action and its supported types and delivery channels.

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 (proactive monitoring) and details the delivery channels, including the always-on feed. However, it does not explicitly mention sibling tools like list_subscriptions or unsubscribe as alternatives for viewing or canceling subscriptions, so it lacks a full when-not-to-use statement.

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 the tool as read-only, open-world, idempotent, and non-destructive. The description adds meaningful behavioral context: results come from the live catalog, outputs are category-bucketed example questions with exact tool and argument shapes, and the tool can be called with or without a topic. This goes beyond the safety profile and informs the agent of dynamic, live 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 longer than minimal but densely informative. It leads with natural-language triggers, then states purpose, output, call variants, and usage guidance, all in one fluid paragraph. Each sentence earns its place, though the many examples could be trimmed slightly without losing meaning.

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

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

There is no output schema, so the description must explain return values, which it does in detail: category-bucketed example questions with exact tool + argument shapes, drawn from a live catalog. It also covers both call modes (full spread vs. topic-focused) and explicitly positions itself as the onboarding entry point, covering the necessary operational and conceptual context for an agent to use it correctly.

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

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

The input schema fully documents the single optional parameter `topic` with an enum-like list of values and behavior when omitted. The description reinforces this with examples ('finance', 'pharma', 'betting') and the focus vs. full-spread distinction, but adds no structural meaning beyond what the schema already states. With 100% schema coverage, the baseline 3 is appropriate.

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

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

The description clearly states the tool is the onboarding entry point for figuring out what to ask Pipeworx, with explicit examples of user intents ('What can I ask Pipeworx?', 'what can you do?'). It also differentiates it from siblings by describing its output (category-bucketed example questions) and its role as a first stop, distinguishing it from tools like ask_pipeworx or discover_tools.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools', providing clear when-to-use context. It also names alternatives (ask_pipeworx, entity_profile, compare_entities) as meta-tools the user can learn about, giving a strong sense of how it fits into a workflow.

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

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

The description adds meaningful behavioral context beyond annotations: ownership is enforced, the row is deactivated not deleted, and historical events remain accessible. This complements annotations like destructiveHint=false and idempotentHint=true by explaining the underlying mechanism and consequences.

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, starts with the action, and provides essential details without any fluff. Every sentence adds value: the first states the core behavior, the second explains side effects and ownership.

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 cancellation tool with one parameter, the description covers the main behavior, ownership constraint, and side effects. It references recent_alerts to connect with other tools. It doesn't describe the return value, but with no output schema, this is a minor gap.

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

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

The input schema fully describes the only parameter 'id' with a clear description (uuid returned by subscribe). The tool description only says 'by id,' which adds no new meaning beyond the schema. Since schema coverage is 100%, the baseline is 3.

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

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

The description clearly states the action ('Cancel') and the resource ('a subscription by id'), making it easy to understand what the tool does. It also distinguishes the tool from siblings like list_subscriptions and subscribe by mentioning ownership enforcement and the deactivation 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 implies when to use the tool: when you need to cancel a subscription you own. It clarifies ownership restrictions and mentions that historical events remain available via recent_alerts, which helps contextualize usage. However, it does not explicitly name 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 readOnly, openWorld, idempotent, and non-destructive, so the bar is lower. The description adds valuable behavioral context: automatic routing, exact percent-delta math for financial claims, fallback to grounded pipeline, and the return of verbatim evidence with a pipeworx:// citation. This goes well beyond the annotations.

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

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

The description is long but well-structured and front-loaded with trigger phrases. Each sentence serves a purpose: usage trigger, path routing, return values, and efficiency claim. It is slightly dense but not wasteful.

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

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

Given there is no output schema, the description compensates by listing the possible verdicts, the grounded/structured value, citation format, and reasoning. It also explains the two distinct processing paths. This is sufficiently complete for a complex tool, though it could be slightly more explicit about response shape.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level detail beyond what the schema provides, though the schema itself already documents both 'claim' and 'tolerance_pct' with examples and tolerance 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 identifies the tool as natural-language claim verification against authoritative sources, with specific trigger phrases ('fact check', 'verify the claim that...') and a concrete resource (authoritative sources, SEC EDGAR + grounded pipeline). It distinguishes itself from sibling tools by specifying its output (verdicts, citations, reasoning) and by stating it replaces 4–6 sequential calls.

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 'Use whenever the agent needs to check whether something a user said is factually correct,' and delineates when the structured SEC/XBRL path applies vs. the fallback grounded pipeline. It does not name alternative sibling tools as exclusions, but the contextual guidance is clear enough for an agent to select it appropriately.

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