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, openWorldHint=true, and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond this: it returns 'stable pipeworx:// citation URIs', claims 'one fast call', and notes availability on 'every tier'. No contradiction exists between description 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 front-loaded well, opening with the decisive 'PREFER OVER WEB SEARCH' and 'START HERE' guidance. However, it is verbose: the long enumeration of data types (SEC filings, FDA drug data, FRED/BLS, patents, weather, etc.) and the seven example queries overlap with the trigger-phrase list and could be trimmed without losing information. It earns its place in the front but drags in the middle.

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 routing tool with no output schema, the description covers a lot: what it does, when to use it, when to escalate to siblings, output format (structured answer with citation URIs), and accessibility (every tier, one fast call). It's missing fine-grained details like response limits or pagination, but given the tool's breadth and the strong annotation coverage, the description is sufficient for an agent to call it correctly.

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

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

Schema description coverage is 100% — the schema fully documents the `question` parameter and all five aliases (q, text, input, query, prompt) with descriptions. The description's examples (e.g., 'Current price of bitcoin') add minor guidance on question phrasing but don't introduce meaning the schema already lacks. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific purpose with concrete verbs ('Routes the question to...', 'returns the structured answer') and identifies the resource (5,635 tools across 1,477 verified sources). It explicitly distinguishes itself from sibling tools ask_pipeworx_grounded and deep_research by naming what they do differently, so an agent can tell them apart without opening their schemas.

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?

Exceptional. It opens with 'PREFER OVER WEB SEARCH', declares itself the 'default entry point' that 'works on every tier', and provides explicit step-up conditions naming alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'. It also gives trigger phrases ('what is', 'look up', 'find') and concrete examples, so when-to-use and when-not-to-use are fully specified.

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

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

The description discloses the beta status, that candidate routing improvements are enabled live when under test, and that no candidate is active currently. It also notes that it is a full working router with no fallback. This goes beyond the readOnlyHint and idempotentHint annotations, adding valuable context about experimental behavior and evaluation. However, it does not describe what changes occur when a candidate is active, which could affect consistency.

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 slightly long but each sentence carries important information: beta nature, current status, usage guidance, evaluation role, and the fact that it is fully functional. It is well-structured and front-loads the key similarity to ask_pipeworx. No fluff; every sentence earns its place.

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

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

For a router with a single required question parameter and no output schema, the description covers its purpose, current state, usage instruction, and relationship to the stable version. It mentions the response shape is identical to ask_pipeworx, which implies the return format. Missing details like error handling or pagination are not critical for a beta router. It is fairly complete 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 schema already documents all parameters (question and its aliases) with 100% coverage. The description adds no additional meaning about parameters, only mentions 'same arguments' as ask_pipeworx without elaborating. Since the schema fully covers parameter semantics, a baseline 3 is appropriate.

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

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

The description clearly states this is a beta version of ask_pipeworx, a universal router that routes questions to 5,635 tools. It distinguishes itself from ask_pipeworx and ask_pipeworx_grounded by naming the stable counterpart and the beta nature. Purpose is specific (routing), but could have explicitly said 'ask a question and get a routed answer' for full clarity.

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

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

It explicitly says to use this when you want the newest routing, and that results are compared against the stable router. It also clarifies that it currently matches ask_pipeworx exactly, so there is no practical difference right now. This gives clear guidance on when to select it over the stable ask_pipeworx, though it does not mention ask_pipeworx_grounded or other alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. The description adds significant behavioral context: it extracts answers only from tool results, returns explicit refusals with specific reasons, and discloses the extra LLM call. No contradiction with annotations, and the added detail goes well beyond the structured hints.

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

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

The description is longer than average but every sentence earns its place—it covers purpose, routing, return shape, refusal reasons, usage guidance, and cost. It front-loads the core concept and keeps information logically ordered. Slight length penalty, but highly efficient for the complexity.

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

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

Given the tool's complexity (multiple refusal reasons, cost, usage distinctions) and absence of an output schema, the description fully explains the return format and refusal semantics. Nothing an agent needs to invoke it correctly 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% (all parameters are documented as aliases for 'question'). The schema already explains the aliases, and the description adds no further parameter-specific detail. Baseline 3 is appropriate when the schema handles the semantics.

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

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

The description clearly states a specific verb-resource ('Hallucination-resistant answer mode') and explicitly contrasts with ask_pipeworx, naming the sibling it is not. It distinguishes by the extraction behavior and use cases, so an agent can tell it apart without opening the schema.

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 ('whenever an answer will be quoted, cited, or acted on'), when not to (prefer ask_pipeworx for casual lookups), and even mentions the cost trade-off (one extra LLM call). This is fully actionable guidance.

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

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

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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description goes far beyond this by disclosing behavioral traits: parallel decomposition across 5,635 tools, gap handling with explicit gaps[] (never invented), contradiction scans, hop iteration semantics, citation_uri resolvability, large-record excerpting (not head-truncated), timing expectations (15-60s, thorough up to ~90s), and account/payment requirements. This is rich behavioral context that heavily outweighs the annotation baseline.

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

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

The description is long (a dense paragraph), but the complexity of the tool justifies the length. It is front-loaded with the critical account requirement and usage guidance, and structured with semicolons and clauses that separate distinct points. Not a wall of rambling — every sentence adds value. Slightly below 5 because it's a single block that could be broken into bullet points, but still well-organized and efficient.

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

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

Covers everything an agent needs to invoke correctly: account prerequisites, fallback alternative if unsigned-in, depth semantics, timing, output format (findings packet with gaps/contradictions), citation behavior, and large-record excerpting. No output schema exists, so the description fully compensates. Nothing important is missing for a correct call.

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%: both 'question' and 'depth' have detailed descriptions in the input schema, including enum values and their behavior. The tool description adds some nuance (e.g., 'standard' re-angles gaps, 'thorough' chases leads) but does not fundamentally go beyond what the schema already documents. Per the rubric, baseline 3 is appropriate when the schema carries the load.

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

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

States a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1477 STRUCTURED data sources... in ONE call'. Explicitly distinguishes from open-web search and siblings like ask_pipeworx, making the tool's niche unambiguous. The description also clarifies what kinds of questions it suits and what it returns (findings packet with evidence, gaps, contradictions).

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Names alternatives directly and ties selection to concrete conditions (account tier, topic type). No ambiguity about which tool to choose.

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 and generic, so the description carries the burden of disclosing behavior. It adds substantial context: the claim_token flow, rate limiting ('5 per identifier per day'), free usage, daily digest review, and roadmap impact. This goes far beyond the structured annotations.

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

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

While longer than average, every sentence carries unique information: purpose, usage triggers, scope exclusion, format guidance, claim_token mechanics, rate limits. Content is front-loaded with purpose and immediately usable directives, 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?

The description covers scope, use cases, rate limits, and claim_token workflow, but does not fully specify return values for the standard filing path (only the claim_token path). Given no output schema exists, this is a minor gap; otherwise the description is complete for its complexity.

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

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

Schema descriptions cover all parameters with high detail (enum values, claim_token usage), so the description adds little new parameter-level information. The only added guidance is formatting feedback in terms of Pipeworx tools/packs and not pasting end-user prompts, which is useful but marginal over 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 clear action ('Tell the Pipeworx team something is broken, missing, or needs to exist') and explicitly lists the feedback categories (bug, feature, data_gap, praise). It distinguishes from sibling tools by scoping to 'tools served by this Pipeworx connection' and clarifies it is not for other MCP servers.

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

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

The description provides explicit triggers for each feedback type ('Use when a tool returns wrong/stale data...', 'when a tool you wish existed isn't in the catalog...', 'when something worked surprisingly well') and a concrete exclusion for tools from other MCP servers. It also explains the claim_token follow-up workflow, giving the agent unambiguous decision criteria.

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

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

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?

Annotations already declare readOnlyHint=true and idempotentHint=true. The description goes beyond by explaining internal cascading lookups ('replaces 2-3 manual lookups'), graceful degradation (if GLEIF or OpenFIGI is unavailable, EDGAR identifiers still return), and the presence of an 'unresolved' field. 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 comprehensive but long, mixing essential guidance ('Use FIRST') with detailed implementation specifics (ISIN-to-LEI mapping details, graceful degradation mechanics). While every sentence adds some value, the length could be reduced by moving some detail to external documentation, making the core purpose more front-loaded.

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

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

Given no output schema, the description does a good job explaining what the tool returns (labeled identifiers, an 'unresolved' field). It covers graceful degradation and the scope of entities. It could explicitly outline the return data structure, but the description adequately prepares an agent to use the tool with confidence.

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

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

Schema coverage is 100% with both parameters described, but the description adds substantial value: it explains that 'value' accepts ticker, CIK, ISIN, or name for companies and brand/generic name for drugs, gives an example (ISIN-to-LEI mapping for CH0038863350), and details what identifiers are returned per type. This richness goes well beyond the baseline of 3.

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

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

The description begins with concrete user queries ('What's the ticker for…') and explicitly states the action: 'resolve a user-spoken NAME to the canonical/official identifiers'. It identifies the specific resources (company identifiers, drug identifiers) and positions itself as the first step before other tools, clearly distinguishing from siblings like compare_entities and entity_profile.

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

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

The description provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It implies the tool is not needed when an ID is already available. It covers supported types and inputs but does not explicitly name alternatives among siblings for cases where an ID is already held, though the context is clear enough for an agent.

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

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

The description 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 readOnlyHint, openWorldHint, and idempotentHint. The description adds crucial behavioral nuance beyond this: it distinguishes 'could_not_verify' (check did not happen, contains verification_error) from 'unsupported' (no source found), and warns that 'could_not_verify' must not be treated as evidence. It also explains the two processing paths and the inclusion of verbatim evidence and citations, going well beyond annotation hints.

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

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

The description is dense and front-loaded with query paraphrases, then states usage, processing paths, return values, and caveats. Every sentence carries meaningful information without filler, but it is long and could be slightly trimmed. Still, it is well-organized and each part 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?

Since there is no output schema, the description takes on the burden of explaining return values: it lists the verdict types, the grounded/structured value with citation, and reasoning. It also covers failure modes and the two processing paths. Missing exact citation format details, but overall it is sufficiently complete for the tool's moderate 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 coverage is 100% for both parameters, so the baseline is 3. The description adds extra meaning by explaining how tolerance_pct overrides claim-wording tolerance and its use in hallucination detection, and by clarifying that the claim is a natural-language sentence. This reinforces and expands on the schema descriptions, earning a 4.

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

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

The description clearly states the tool's purpose: verifying natural-language factual claims against authoritative sources, with specific verbs like 'fact check', 'verify', 'confirm or refute'. It distinguishes itself from sibling tools by describing the two processing paths (SEC EDGAR fast path vs grounded pipeline) and by noting it replaces 4–6 sequential calls, making it a unique higher-level tool.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct', providing a clear usage context. It also differentiates company-financial claims from other factual claims. It does not name alternative tools or explicitly state when not to use, but the 'Replaces 4–6 sequential calls' note implies it is a consolidation tool, offering strong guidance.

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