Klaviyo

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is known. The description adds useful context: the default model is free, probing Anthropic requires an _apiKey with direct payment to Anthropic, and it returns per-model plus combined results. This exceeds 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 three sentences, front-loaded with the core purpose, then covering model options, return format, and use cases. Every sentence contributes meaningful information with no redundancy.

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

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

Despite no output schema, the description states the return structure: 'per-model {score, confidence, signals, raw_response} + a combined view.' It covers defaults, external API calls (Anthropic), and practical use cases, making it complete for a read-only probe tool.

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

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

Schema description coverage is 100%, giving baseline 3. The description adds extra meaning by explaining the default model ('Workers AI Llama-3.3-70b (free)'), that _apiKey is passed straight through to Anthropic, and that context disambiguates common names. This compensates 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 function: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This specific verb+resource+output distinguishes it from siblings like ask_pipeworx or compare_entities, making the purpose unambiguous.

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

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

It provides explicit use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also clarifies the default model and how to include Anthropic with a BYO key. However, it does not name alternative sibling tools or explicitly 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 meaningful behavioral context: it routes to thousands of sources, fills arguments internally, returns citation URIs, is a single fast call, and works on every tier. It stops short of disclosing failure modes or rate limits, so not a perfect score.

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 verbose but front-loaded with the most critical instruction ('PREFER OVER WEB SEARCH') and structured with concrete examples and a clear 'step up only when needed' section. Some sentences could be trimmed, but the overall flow is logical and informative.

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 meta-tool with no output schema, the description explains the return format (structured answer with citations), the breadth of sources, and when to use alternatives. It lacks precise details on output fields or error behavior, but covers the essential context for an agent to select and invoke the tool correctly.

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

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

The schema covers 100% of parameters with descriptions and alias handling. The description's example questions are illustrative but do not add significant semantic meaning beyond the schema, so the baseline of 3 for high schema coverage 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: it routes questions to 5,439 tools, fills arguments, and returns structured answers with stable citations. It explicitly distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research, making its purpose unmistakable.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', lists trigger phrases like 'what is' and 'look up', and provides step-up conditions to use ask_pipeworx_grounded or deep_research. This is textbook usage guidance with named alternatives and clear exclusion criteria.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond annotations: it discloses the experimental nature, the fact that candidate routing improvements may be active live, the current state (no active candidate since 2026-07-26), and that it falls back to nothing. This provides transparency about how behavior may differ from ask_pipeworx.

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 with useful details—beta status, identical tool set, experimental nature, current state, usage guidance—and each sentence contributes meaning. It is slightly longer than necessary but remains well-structured and front-loaded with the most important information.

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

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

Despite having no output schema, the description explains the response shape is identical to ask_pipeworx, and covers the tool's purpose, current behavior, experimental edge, and fallback semantics. For a single-question router tool, this is complete and leaves no critical gaps.

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

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

Schema coverage is 100%, so the schema already fully documents the 'question' parameter and its five aliases. The description only says 'same arguments' and doesn't add parameter-level detail, but given complete schema coverage, the parameter semantics are adequately handled by the schema alone.

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

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

The description clearly identifies ask_pipeworx_beta as a beta version of ask_pipeworx that routes to the same 5,439 tools with identical arguments and response shape, but with candidate routing improvements when under test. This distinguishes it from its siblings ask_pipeworx and ask_pipeworx_grounded, and states its current behavior (matches ask_pipeworx exactly).

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 it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It also clarifies that it is a full working router with no fallback, giving clear context on when and how to use it versus the stable alternative.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the exact refusal behavior, return format (with evidence, confidence, source), and the refusal_reason enum. It also reveals the extra LLM call cost and the fact that it picks from 5,439 tools, adding significant context beyond annotations without contradiction.

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

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

The description is front-loaded with the core purpose, then details, then usage guidance, and ends with cost consideration. Every sentence contributes new, actionable information, with no fluff. Despite its length, it remains focused and 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?

Given the absence of an output schema, the description provides a thorough account of return values for both success and failure paths, enumerates refusal reasons, and explains the rationale for use in high-stakes scenarios. It is complete for a tool of this complexity.

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

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

The input schema already documents all six parameters (all aliases for 'question') at 100% coverage. The description adds no additional parameter-specific semantics, and since the schema is fully descriptive, the baseline of 3 is appropriate. It does mention that the tool 'fills arguments' but does not elaborate on the question field.

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

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

The description immediately identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads' and clearly explains its function: it routes through the same pipeline as ask_pipeworx, fetches data, and extracts an answer using only the tool result. This distinguishes it from siblings like ask_pipeworx and validate_claim by emphasizing groundedness and refusal 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?

Explicit guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on' and 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This clearly states when to use this tool and when to use an alternative, satisfying the highest standard.

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

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

The description goes far beyond the annotations: it reveals resolver behavior (market_match_confidence, score, alternatives, suggestions), the 24h-move warning, statuses like low_confidence_match and market_closed_or_inactive, illiquid_wide_spread handling, news fallback fields, and cancellation-rule parsing with EV impact. This is rich, safety-critical behavioral context that annotations alone (readOnlyHint, openWorldHint) do not provide. 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 densely packed with actionable, non-redundant information. It uses clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) to aid scanning. A few sections (e.g., multiple news fallback details) could be trimmed, but for a tool with this complexity, the length is justified and every sentence provides value.

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

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

With no output schema, the description carries the full burden of explaining return values. It thoroughly covers result.market, result.analysis, result.evidence, resolver fields, parent_event, news fields, status values, and risk warnings. It even describes failure modes (low-confidence short-circuit, de-indexed markets) and their blocking behavior. This is a complete picture for agent invocation and result interpretation.

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

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

Schema coverage is 100% and the schema already explains each parameter (market as slug/URL/question text, depth enum, include_raw boolean). The description adds examples of fan-out behavior but does not significantly augment parameter-level semantics beyond what the schema provides. Baseline 3 is appropriate given high schema coverage.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes this from sibling tools like polymarket_edges or polymarket_arbitrage by emphasizing one-call research, market resolution, classification, fan-out, and evidence packet production. The scope is fully specified.

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 use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' and gives category examples. However, it does not explicitly name sibling tools as alternatives or exclusions (e.g., when to use polymarket_edges instead). Still, the context is clear enough for an agent to decide when to invoke this tool.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior, but the description adds substantial context beyond that: it explains data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), correct handling of off-calendar fiscal years, sorting by primary metric, and output includes paired data plus citation URIs. This is exactly the kind of behavioral context that is valuable 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 front-loaded with trigger phrases and concise examples, making it easy to scan. It is somewhat long, but every sentence adds meaningful information (data sources, fiscal year handling, sorting, output format). It is structured logically, starting with usage triggers, then operational details, then benefit over alternatives. No wasted words, but could be slightly tightened.

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 does a good job explaining what the response will contain ('paired data + pipeworx:// citation URIs per entity', sorted by primary metric). It covers entity types, count limits, data sources, and key behavioral edge cases (off-calendar fiscal years). It doesn't describe error handling or pagination, but for a read-only comparison tool, the essentials are covered.

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%, but the description enriches both parameters significantly. For 'type', it details what each enum value means (company pulls 10-K financials, drug pulls adverse-event and approval counts). For 'values', it clarifies the entity format (tickers/CIKs vs names) and shows examples. This goes well beyond the basic schema descriptions.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call, with specific trigger phrases like 'X vs Y' and 'which is bigger'. It distinguishes itself from sequential single-pack lookups and specifies what data each type pulls. The verb+resource+scope is precise and unambiguous.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a clear directive on when to use this tool. It also names the alternative (sequential lookups) and gives context for both company and drug use cases. This qualifies as explicit when/alternative 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 read-only, open-world, idempotent, non-destructive. The description adds substantial behavioral context beyond these: it decomposes questions into facets, routes to 5,439 tools in parallel, returns gaps[] and contradicts[], never invents evidence, uses semantic excerpting, and provides timing expectations (15-90s). No contradictions with annotations.

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

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

The description is long but information-dense and well-structured, front-loading the account gating and core purpose before diving into edge cases and depth semantics. Every sentence earns its place. It loses one point only because its length may require extra parsing effort, but it avoids redundancy and maintains clear logical flow.

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 covers return values (findings packet, gaps[], contradictions[], hop field, citation_uri). It also addresses prerequisites (account), timing, depth variations, and exclusions. Given the tool's complexity and the absence of an output schema, the description is exceptionally 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% and parameters are simple (question, depth). The description enriches both parameters significantly: it explains the natural-language format for question ('Broad/multi-part is fine') and details the depth enum behavior ('quick=3 (single hop), standard=5 (adds gap-recovery + contradictions), thorough=8 (paid; adds full iterative hop + contradictions)'). It also describes the return packet structure, which is essential given no output 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 precisely states the tool's function: 'Grounded multi-source research across Pipeworx's 1412 STRUCTURED data sources' and 'Decomposes your question into focused facets, routes each to the right one of 5,439 tools IN PARALLEL.' It explicitly distinguishes itself from open-web search and from sibling ask_pipeworx, making the purpose and scope unmistakable.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data.' It also names alternatives and exclusions: 'For a single lookup use ask_pipeworx (one LLM call, not many)' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' Additionally, it states the account requirement and fallback to ask_pipeworx if not signed in, making trade-offs 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, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: returns top-N results, includes full input schemas with curated examples, and each result is ready to call directly with no second schema lookup. This enriches the output-format understanding 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 a single dense paragraph with no filler. It leads with the primary action, then lists relevant domains, then explains the return value, and ends with a clear usage directive. Every sentence contributes essential information for tool selection and invocation.

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

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

Given the tool's moderate complexity and the presence of informative annotations and a complete schema, the description adequately covers return behavior and usage. It could mention what happens when no tools match (e.g., empty results), but that is a minor gap for a discovery tool. Overall, an agent can effectively decide when and how to invoke it.

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

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

Schema coverage is 100%, with the 'query' parameter having a detailed description, aliases, and examples. The description adds little parameter-specific meaning beyond 'describing the data or task' and the 'top-N' phrase that maps to 'limit'. Per the rubric, high schema coverage makes the baseline 3, and the description only marginally supplements it.

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

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

The description opens with 'Find tools by describing the data or task', a specific verb+resource statement. It enumerates many domains (SEC filings, FDA drugs, etc.) and clearly distinguishes itself as a discovery/meta-tool, unlike siblings that are concrete data-lookup tools. 'Call this FIRST when you have many tools available' reinforces its unique role.

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

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

It explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available'. It adds an implicit exclusion with 'not just one answer', but does not name specific alternative tools or state when not to use it, so it falls short of a full 5.

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

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

Annotations already declare the tool safe (readOnly=true, destructive=false), but the description adds valuable behavioral specifics: patent API sunset soft-fail, GDELT→GNews fallback for news, 'LATEST 10-K ... sorted period_end DESC', filing URIs, and the 'ONE parallel call' execution model. These go well beyond the annotations to set accurate expectations.

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

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

The description is dense but every section earns its place: example triggers, the core promise, usage preference, source list, return fields, parameter format, and a critical limitation. There is no unnecessary padding, and the information is front-loaded with the most important purpose statement.

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 full responsibility for explaining return values, and it does so thoroughly: CIK/name, up to 5 filings with URIs, fundamentals fields with sorting, patent status, news fallback chain, and LEI. It also covers the ticker/CIK input constraint and points to resolve_entity for names, making the tool's scope and behavior fully comprehensible.

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 has 100% coverage with detailed descriptions for both parameters (type enum, value as ticker/CIK with name limitation). The tool description essentially restates these same details without adding new semantic meaning, 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 clearly states this tool creates a 'full cross-source profile of a US public company in ONE parallel call' and lists specific outputs (CIK, filings, fundamentals, patents, news, LEI). It uses specific verbs and resources, and distinguishes itself from single-pack SEC/XBRL/news lookups by emphasizing the holistic 'ALWAYS PREFER' directive and the parallel fan-out across sources.

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

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

Explicitly says when to use it ('when the user asks for a holistic view') and when not to use it ('names not supported'), directing users to resolve_entity for name-based queries. It also contrasts with chaining multiple lookups, making the decision boundary 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 flag destructiveHint and idempotentHint, and the description adds context about what is affected ('previously stored memory', 'sensitive data the agent saved earlier'). It does not disclose error behavior or irreversibility beyond the delete action, so it falls just short of a 5.

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 concise sentences, fully front-loaded with the action, then usage context, then sibling tools. No filler or redundant wording.

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

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

For a one-parameter destructive memory operation with annotations covering destructiveness and idempotency, the description is complete: it covers purpose, when to use, and related tools. No output schema is needed for this simple delete action.

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

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

Schema description coverage is 100% and the key parameter is already described as 'Memory key to delete'. The description merely repeats 'by key' without adding format, edge-case, or lifecycle semantics, 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 clearly states 'Delete a previously stored memory by key', using a specific verb and resource. It also distinguishes itself from sibling tools by explicitly naming 'remember' and 'recall' as partners, making its role 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 provides explicit usage scenarios: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names the related tools remember and recall, giving direct alternatives/complements.

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

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

The description explains the tool's behavior beyond the annotations: it fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format. This adds useful context about the workflow and output, and no contradictions with the readOnlyHint or other annotations are 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?

The description is concise, front-loaded with the main purpose, and follows with use cases. It uses two sentences plus a short list, making it efficient without being terse. It earns a high score but slightly misses the mark of 5 due to some redundancy (e.g., 'production-ready' and 'standard llms.txt markdown format' could be simplified).

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

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

The description fully covers the tool's behavior, output format, and intended scenarios. With only two parameters, no output schema, and annotations providing safety context, the description is complete enough for an agent to select and invoke the tool correctly. No critical gaps are evident.

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 (url and max_links) with 100% coverage. The description only reiterates that the URL can be a full site or landing page, which adds little beyond the schema. According to the calibration rules, a high schema coverage warrants a baseline score 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 explicitly states the tool generates a production-ready llms.txt file for any URL, with a clear verb ('generate') and resource ('llms.txt file'). It also mentions the intended use cases, distinguishing it from sibling tools that focus on auditing AI presence rather than generating the file itself.

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 with three specific use cases (client sites, own projects, competitor auditing). It does not explicitly state when not to use the tool or name alternative tools, but the use cases imply when it 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety profile. The description adds behavioral context by listing what the tool returns (name, status, subject line, recipient list, performance stats, send history), which goes beyond the annotations. No contradictions.

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

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

A single, well-structured sentence that starts with the verb and resource, then succinctly lists the major return contents. No wasted words, every phrase adds value.

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

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

For a simple get-by-ID tool with only 2 fully documented parameters, rich annotations, and an output schema, the description is complete. It doesn't need to explain return values in depth since the output schema exists, and the listed return fields are sufficient.

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 (_apiKey and campaign_id) already described. The description adds only 'by ID' which slightly reinforces campaign_id's purpose but does not meaningfully enhance the schema's parameter semantics. Baseline 3 is appropriate.

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

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

The description uses the specific verb 'Get' with the resource 'a campaign's full details by ID', clearly distinguishing this from sibling tools like klaviyo_list_campaigns (listing) and klaviyo_get_profile (profiles). It also enumerates the key data returned, making the tool's scope unambiguous.

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

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

The phrase 'by ID' and 'full details' clearly imply usage when a specific campaign ID is known and comprehensive information is needed. It does not explicitly state exclusions or direct alternatives, but the context plus sibling names make the appropriate use case clear. No misleading 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 and idempotent, so the safety profile is covered. The description adds valuable behavioral context by listing the fields returned ('email, name, phone, custom properties, list memberships, and subscription status'), which enriches understanding of what the tool does beyond the annotations. It does not discuss rate limits or potential pitfalls, but with strong annotations this is sufficient.

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

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

The description consists of two clear, front-loaded sentences. The first sentence states the core purpose, and the second summarizes the return value. There is no extraneous information, making it highly concise and well-structured.

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

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

The tool is simple (get by ID) and the description, combined with the annotations and the presence of an output schema, provides sufficient context. It tells the user exactly what data will be returned, making the description complete for a read-only lookup 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 input schema provides 100% coverage with descriptions for both parameters ('Klaviyo private API key' and 'Klaviyo profile ID'). The description itself does not elaborate on the parameters, aligning with the baseline 3 for high schema coverage.

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

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

The description clearly states the tool's function: 'Get a contact's full profile by ID.' This specifies the action (get), the resource (contact's full profile), and the method (by ID). It distinguishes from sibling tools like klaviyo_list_profiles which lists profiles, by emphasizing single-profile retrieval via a specific identifier.

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 have a profile ID and need a comprehensive profile. It clearly indicates the need for an ID, which is a clear context. However, it does not explicitly name alternatives or provide exclusion criteria, stopping short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds value by specifying the response contents (campaign IDs, names, status, send dates, performance metrics), which goes beyond the structured metadata. It does not mention pagination or API-specific quirks, but this is acceptable given the annotation coverage.

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?

A single, front-loaded sentence conveys the purpose, key filter dimension, and return values. There is no redundancy or irrelevant detail, making it highly 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?

The tool is simple (two parameters, one required), has full schema coverage, and has an output schema. The description covers the essential behavior and return summary. There are no significant gaps that would hinder correct invocation.

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

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

Schema coverage is 100%, so parameter basics are already documented. The description adds meaning by clarifying that the filter is primarily for status and enumerating the status values (draft, scheduled, sent), which aligns with the filter parameter's purpose beyond the schema example.

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 ('Search') and a resource ('campaigns'), and clearly states the filtering dimension (status: draft, scheduled, sent) and the returned fields. This distinguishes it from sibling tools like klaviyo_get_campaign (single campaign) and klaviyo_list_lists/profiles (other resources).

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 searching campaigns by status and lists the applicable statuses. It does not explicitly mention alternatives or exclusions, but the context is clear enough for an agent to choose this tool over the sibling 'get_campaign' tool.

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

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

Annotations already disclose read-only, idempotent, non-destructive behavior, lowering the bar for the description. The description adds return field details (list IDs, names, subscriber counts, creation dates), but this is output-oriented rather than deep behavioral context (e.g., pagination, rate limits, auth specifics). It doesn't contradict annotations, and the added value is modest, aligning with a 3.

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 core action ('Get all email lists') followed by return contents. There is zero fluff or redundancy, making it perfectly concise.

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

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

For a simple list tool with one parameter, rich annotations, and an output schema, the description covers the essential purpose and return data. It doesn't mention pagination or limits, but 'all' suggests completeness. Given the low complexity, this is nearly complete, though a note about data freshness (given openWorldHint) could push it higher.

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

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

Schema description coverage is 100% for the single parameter (_apiKey), so the description doesn't need to explain it. The description adds no extra meaning beyond the schema, meeting the baseline of 3 for high schema coverage.

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

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

The description uses a specific verb and resource ('Get all email lists') and clearly distinguishes this from sibling tools like klaviyo_list_campaigns and klaviyo_list_profiles by focusing on email lists. It also specifies the return payload (IDs, names, subscriber counts, creation dates), 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 implies when to use the tool (when you need email lists) by clearly scoping to 'email lists in your account.' While it doesn't explicitly mention alternatives or exclusions, the context is sufficient for an agent to differentiate from sibling list tools. It lacks explicit 'when-not-to-use' guidance, so it falls short of a 5.

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

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

The description discloses return fields (profile IDs, emails, names, properties) and pagination support, which adds context beyond the annotations' read-only and idempotent flags. It doesn't contradict annotations and provides useful behavioral details.

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 resource, with no unnecessary words. It is concise and well-structured.

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

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

Given the tool's simplicity, the description covers the main purpose, return values, and pagination. The output schema handles details, and annotations cover safety, so this is adequately complete for selection and invocation.

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

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

The schema already documents all three parameters with descriptions. The description adds that filtering can be done by email, name, or custom attributes, which enriches the generic filter parameter and clarifies intended usage.

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 'Search contacts by email, name, or custom attributes,' which is a specific verb (search) and resource (contacts). This clearly distinguishes from sibling tools like klaviyo_get_profile (single profile) and klaviyo_list_lists (lists).

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 explicit guidance on when to choose this tool over alternatives. It only states what it does, leaving the agent to infer usage without exclusions or alternative recommendations.

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 value by disclosing the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and specifying scope ('caller's active subscriptions'). This goes beyond the annotations, though it could have mentioned the include_inactive parameter behavior more explicitly.

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

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

Two sentences are concise and well-structured: first states the core action, second lists return fields and usage context. No wasted words, information is front-loaded and easy to parse.

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

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

For a simple list tool with one optional parameter, the description is complete: it identifies the resource, the output structure, and typical use cases. Annotations cover safety and idempotence, and the schema covers the parameter. 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?

The schema fully describes the only parameter include_inactive with 100% coverage, so the description need not add much. The description does not discuss the parameter, but the schema carries that burden. Baseline 3 applies.

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

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

The description clearly states the tool's purpose: listing the caller's active subscriptions. It specifies a concrete action and resource, and differentiates from siblings like subscribe and unsubscribe by mentioning use cases for reviewing before adding more or finding an ID to cancel.

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 when to use the tool: 'to review what you're monitoring before adding more or to find an id to cancel.' This provides clear contextual guidance and implicitly distinguishes it from subscription creation/cancellation tools, giving actionable usage direction.

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

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

Annotations are all false and provide no safety signals, but the description carries the burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), quota exemption ('Free; doesn't count against your tool-call quota'), processing cadence ('team reads digests daily'), and privacy guidance ('don't paste the end-user's prompt'). These behavioral details are rich and go well beyond the minimal annotation set.

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 8 sentences but every one earns its place: purpose statement, when to use, when not to use, disambiguation, content guidelines, impact reassurance, rate limit, and quota note. It is front-loaded with the most critical information and flows logically, with no fluff 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?

There is no output schema, but for a feedback submission tool the description covers all essential context: what to report, how to structure it, exclusions, behavioral constraints, and processing expectations. It is complete enough for an agent to select and invoke this tool correctly without needing external documentation.

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

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

Schema coverage is 100% with descriptions for every parameter, so the baseline is 3. The tool description goes further by reinforcing the 'describe in terms of Pipeworx tools/packs' guidance and advising against pasting the user's prompt, which directly informs how to fill the 'message' and 'context' fields. This adds useful context beyond the schema, justifying a 4.

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

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

The description opens with a clear verb+resource statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then elaborates specific categories (bug, feature/data_gap, praise) that map directly to the 'type' enum. It distinguishes this tool from siblings by explicitly restricting scope to Pipeworx-served tools only, which is unique among the listed sibling tools.

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

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

The description gives explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear when-not-to-use exclusion: if the tool came from a different MCP server, file with that server instead. This fully addresses selection boundaries.

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

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

Annotations already mark it read-only and non-destructive, but the description adds valuable behavioral context: it is self-aggregating, derived from CF analytics-engine, contains no PII, returns only (pack, tool, count), and has a cache freshness of 5min-1h depending on window. This fully discloses the data source, privacy implications, and potential staleness.

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

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

The description is appropriately sized and well-structured. It opens with a concise one-sentence summary, then lists specific return contents, followed by bullet-like use cases, and ends with essential technical details. Every sentence adds distinct value with no redundancy.

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

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

For a simple read-only tool with no output schema, the description covers the essential context: what is returned, the time windows, use cases, data source, privacy, and caching. It does not specify the exact return format (e.g., array structure), but that is not critical given the output is described conceptually as 'top tools, top packs, total call volume'.

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 single parameter 'window' is fully described in the schema with defaults and trade-offs between short and long windows. The description merely restates the window options without adding new semantics, 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 clearly states the tool's function: reporting what other AI agents are calling on Pipeworx, with specific outputs (top tools, top packs, total call volume). It distinguishes itself from siblings like discover_tools by explicitly focusing on real-time agent usage trends rather than general discovery.

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

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

The description provides three explicit use cases: discovering hot data sources for current events, confirming a canonical tool choice, and checking alignment with typical agent needs. While it does not mention when not to use it or name alternatives, the given scenarios offer clear practical 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 goes well beyond the annotations by detailing internal filters (semantic Jaccard ≥0.30, partition placeholder drop >20%), the fill check against live CLOB depth, and the exact behavior in each mode. It also discloses what counts as a non-tradeable signal, adding substantial context the annotations do not provide.

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

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

The description is lengthy but appropriately so for a tool with two modes, multiple filters, and a fill-check subprocess. It is front-loaded with the core purpose, then uses clear labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and structured response details. Every sentence contributes necessary operational information.

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

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

Given the absence of an output schema, the description thoroughly explains the response shape (opportunities[], partition_check fields, fill_check outputs) and all behavioral edge cases across modes. It covers no-arg, event, and topic usage, plus filtering and tradeability constraints, making it fully self-contained.

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

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

Although the schema already describes the two parameters at 100% coverage, the description adds rich semantic context: examples of valid slugs and seed questions, what happens when each is passed, and the fact that calling with no arguments triggers a trending_scan. This adds meaning beyond the schema field 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 and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from sibling tools like polymarket_edges and polymarket_edge_tracker by naming the unique detection mechanisms and 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?

Explicit guidance is given for each invocation style: no args for trending_scan, 'event' for single-market partition checks, and 'topic' for cross-event scanning. It also points to an alternative, polymarket_fill_risk, for custom sizing, and advises against trading when realizable_edge_pp ≤ 0.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, and the description adds substantial context: caching at KV level for 1 hour, a 24h-move warning that edge may already be priced in, and the design that partition_overround returns kelly_fraction_half=0 at parent level. It also explains why segments can be empty via _diagnostics, exposing internal funnel counters.

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 meticulously organized with uppercase section markers (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). It is front-loaded with purpose, and every sentence adds operational detail, though the sheer length could be overwhelming for an agent needing a quick 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 there is no output schema, the description fully compensates by detailing the top-level response structure (by_segment, fed_candidates, _diagnostics) and the meaning of each segment. It also covers edge cases like placeholder-slug filters, partition constraints, and why segments might be empty, making it complete for a tool of this complexity.

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

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

The input schema has 100% description coverage for all 9 parameters, giving a solid baseline. The description adds semantic meaning beyond the schema by explaining the 'tradeable-edge knobs' (min_liquidity, max_spread_pp) and providing real-world slippage context (zero fees but 20-50bp bid/ask cost). The min_kelly and min_partition_leg_kelly distinction is particularly well clarified.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes itself from sibling tools by covering three model families and framing itself as a discovery tool for 'what should I bet on today,' avoiding page-by-page market scanning.

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

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

The description provides clear context: built for discovering bet opportunities without paging hundreds of markets, and notes that Fed bets are excluded from ranking due to unreliable signals. It doesn't explicitly name alternatives or provide 'when not to use' exclusions, but the use case is strongly implied.

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

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

Even though annotations declare readOnlyHint=true and idempotentHint=true, the description adds substantial behavioral detail: it explains the response structure (tracked[], expired[], snapshot_dates[]), what each field means (e.g., trend, decay_pp_per_day, lifespan_days), how snapshots are created (cache-miss writes), and the exact computational basis (daily closes of edge_pp_net, not intraday). This goes far 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 into distinct sections: core purpose, Args, RESPONSE, and LIMITS. Every sentence contributes value—the persistence insight, the field definitions, the snapshot-gap explanation. It front-loads the most important concept and structures details logically, making the length justified.

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

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

With no output schema, the description fully compensates by detailing the response structure: tracked[] with edge_pp_net time-series, first_seen, trend, decay_pp_per_day; expired[] with lifespan_days; snapshot_dates[]. It also discloses data freshness (TTL, gaps, snapshot start). This makes the tool's behavior and return values completely transparent.

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 gives complete descriptions for both parameters (days, window) with defaults and ranges (clamp 2-30, enum values). The description's 'Args' section merely repeats this information with a slight simplification ('max 30' vs 'clamp 2-30'). Since schema coverage is 100%, the description adds little new meaning beyond confirming defaults.

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

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

The description opens with 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots,' a specific phrase that clearly states what the tool does and distinguishes it from siblings like polymarket_edges (which likely only returns current edges). It further clarifies the core question it answers: 'how long has this edge existed and is it shrinking?'

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 frames the use case: a fresh wide edge vs. a 3-week-old wide edge are different trades, implying this tool is for assessing edge persistence/decay over time. It also notes limitations (60-day TTL, snapshot gaps) that affect when results may be incomplete. However, it doesn't explicitly name alternatives or say 'when not to use,' 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 indicating read-only, idempotent, non-destructive behavior, the description adds substantial operational detail: it walks the order-book ladder, returns specific metrics per mode, explains how partial fills can strand the user unhedged, and names key risk outputs. This goes well beyond the annotations' basic safety profile.

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

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

The description is dense but well-structured with clear mode sections (SINGLE-MARKET vs BASKET) and a usage directive at the end. Every sentence carries substantive information, though its length is notable; it earns a high score for delivering high information density without redundancy.

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

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

Given the tool's complexity (two modes, no output schema), the description is remarkably complete: it enumerates return fields for both modes, explains interpretation (verdict, capture_ratio, thin_legs, forced_directional_risk), and covers edge cases like partial fills and thin books. The guidance on when to use is also fully integrated.

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 parameter meaning significantly: explains size_usd semantics differently for buys vs sells and for basket mode (settlement notional, shares per leg, $1 payout), clarifies side defaults per mode, and defines the market/event distinction. This adds value beyond the schema's field-level descriptions.

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

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

The description clearly states the tool's function: a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes two modes (single-market and basket) and differentiates from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk and execution feasibility.

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: before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500. Also explains the reasoning (theoretical overround on thin books is not capturable, partial basket fills convert arbs to unhedged positions), giving clear context and exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, but the description adds substantial behavioral context beyond that. It discloses the compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and the meaning of matched_pairs:0 with various skip configurations. It also clarifies that 'no arb exists' when bet shapes differ, which is critical behavioral insight. No contradiction with annotations.

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

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

The description is long and dense, but it is organized into recognizable segments (TWO MODES, RESPONSE, SAFETY FIELDS) with all-caps headers that aid scanning. Every sentence carries meaningful information; no filler. The length is justified by the tool's complexity and the absence of an output schema, though the prose style requires careful reading.

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 must fully explain return values and edge cases, and it does. It covers the structure of the response (leg-by-leg prices, top_spreads_pp), the compatibility_warning trigger conditions, temporal_alignment semantics, and the meaning of skip counters. Nothing essential is missing for an agent to decide when and how to invoke the tool correctly.

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

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

Although the schema description covers all three parameters individually, the tool description adds crucial interaction semantics: explicit kalshi_event_ticker and polymarket_event_slug override the topic-mapped side. It also explains the dual-mode behavior and that the topic parameter accepts a predefined enum list, which is fully spelled out. This goes beyond the schema's basic field descriptions.

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

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

The description clearly identifies the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This specific verb+resource distinguishes it from sibling Polymarket-only tools. It also details two operational modes (topic shortcuts vs explicit tickers) with concrete examples, making its function unmistakable.

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

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

The description explicitly explains when to use each mode, including how parameters override topic mappings. It provides strong when-not guidance: 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable' and explains when spreads are meaningful versus when they are not (e.g., non-equivalent bet shapes, temporal misalignment). This is explicit usage context beyond a simple alternative list.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds useful context about scoping (anonymous IP, BYO key hash, or account ID) and the key-omission listing behavior, which goes beyond annotations. 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 three sentences, front-loaded with the main action. Every sentence earns its place: purpose, usage guidance, scoping, and sibling tool context. No filler or redundancy.

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

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

For a tool with one optional parameter and no output schema, the description covers retrieval, listing, scoping, and complementary tools. It provides enough detail for an agent to select and invoke the tool correctly without needing additional context.

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

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

Schema coverage is 100% with the key parameter already described as 'Memory key to retrieve (omit to list all keys)'. The description reinforces this and adds the pairing context with remember/forget, but the incremental semantic value is modest 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?

Description clearly states the tool retrieves a saved value via remember or lists all saved keys when key is omitted. It uses a specific verb (retrieve) and resource (memory key), and explicitly contrasts with sibling tools remember and forget.

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

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

Description explicitly says 'Use to look up context the agent stored earlier' and instructs to pair with remember to save and forget to delete. This provides clear when-to-use and alternative guidance, including the scenario of listing all keys.

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 that setting mark_read:true will flag events as read and alter future results, which contradicts the readOnlyHint annotation that indicates no state changes. Since the annotation is present, this is a contradiction; the description itself is transparent, but the conflicting signals confuse the agent.

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

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

Five sentences, each adds value: purpose, return payload, filtering, mark_read behavior, and alternative endpoint. 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?

Coverage is strong for a read tool: purpose, filtering, side-effect of mark_read, and alternative access. It doesn't detail every parameter's behavior (e.g., unread_only interaction), but schema handles those details; the lack of output schema is partially compensated by describing return fields.

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

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

The schema already covers all five parameters with descriptions, so the baseline is 3. The description adds valuable context by giving an example type ('sec_8k'), explaining the ISO timestamp format for 'since', and elaborating on the consequence of mark_read, pushing it to 4.

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

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

The description opens with a specific verb ('Pull') and resource ('fired events from your subscription feed'), and clarifies it returns recent alerts from the evaluator. This distinguishes it from sibling tools like 'recent_changes' by focusing on subscription-feed alerts.

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

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

It explicitly mentions filtering by type and since, and notes polls work fine, recommending an alternative HTTP endpoint for scripts/dashboards. However, it doesn't explicitly name sibling tools or state when not to use this tool, though the alternative implies a boundary.

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

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

Annotations already indicate readOnly/idempotent/non-destructive, but the description adds valuable behavior: fans out to multiple sources, GDELT→GNews fallback on rate limits/5xx, PatentsView API sunset and soft-fail, and return format including citation URIs. No contradiction with annotations.

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

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

The description is dense but well-structured: opens with natural-language query examples, then details sources, fallbacks, parameter formats, and return shape. Every sentence adds value, though it is longer than strictly necessary. Slight trimming could make it more streamlined.

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

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

For a multi-source aggregation tool with no output schema, the description is highly complete: it lists sources, fallback logic, date formats, return structure (changes[] grouped by source, total_changes, pipeworx:// URIs), and even alternative tool references. The complexity is well covered.

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

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

Schema already describes all 3 parameters, but the description adds meaningful detail: `since` accepts ISO dates or relative shorthand with examples ('7d', '30d', '3m', '1y'), recommends '30d' or '1m' for monitoring, and clarifies that `value` accepts ticker or zero-padded CIK. This goes beyond schema coverage.

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

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

The description states a specific verb+resource: 'change feed for a company in the last N days/weeks/months' with explicit data sources (SEC EDGAR, GDELT/GNews, USPTO). It distinguishes from sibling entity_profile by explicitly naming the alternative for static profiles.

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 when-to-use guidance via query examples ('What's new with X') and explicit alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' Also explains fallback behavior across sources and notes USPTO soft-fails until reactivated.

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

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

Annotations already indicate a non-readonly, idempotent, non-destructive operation. The description adds valuable context beyond this: key-value scoping by identifier, persistence differences between authenticated (persistent) and anonymous (24-hour) sessions, and pairing with recall/forget. This supplements the annotations meaningfully 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 succinct sentences: purpose, usage scenario, and key behavioral details. Every sentence contributes essential information, with no redundancy or filler.

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

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

For a simple two-parameter write tool with no output schema, this description covers purpose, usage, retention, scoping, and companion tools. It is fully sufficient for an agent to decide when and how to invoke it correctly.

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

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

Schema coverage is 100% with clear descriptions and examples for both key and value. The description does not add further parameter-specific meaning beyond noting it's a key-value pair, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool saves data for later reuse, with specific examples (resolved ticker, target address, user preference). It distinguishes itself from sibling tools by explicitly mentioning recall and forget as complementary operations.

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

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

It provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also names alternatives (recall, forget) and their roles, giving clear context for choosing this tool over siblings.

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

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

The annotations already mark it read-only and idempotent, but the description adds valuable behavioral details beyond that: the internal cascade through multiple lookup endpoints, auto-disambiguation for company inputs, and the specific return fields with source citations (SEC EDGAR, RxNorm). 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 longer than a single sentence, but it is well-structured with a trigger-phrase section and 'SUPPORTED TYPES' clearly labeled. Every sentence conveys useful info (examples, sources, return fields, cascade justification), so it remains efficient despite its length.

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

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

With no output schema, the description fully specifies what is returned for each entity type, including citation URIs. It also explains the internal complexity (cascading lookups) and why the tool saves multiple manual steps, giving the agent a complete understanding for selection and invocation.

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

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

Schema coverage is 100%, so baseline is 3, but the description enriches the parameters significantly by detailing accepted formats for 'value' (e.g., 'ticker, CIK, or name' for company; 'brand or generic' for drug) with concrete examples like 'ozempic' and 'metformin'. This adds real semantics 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 resolves user-spoken names to canonical identifiers, with specific examples ('ticker', 'CIK', 'RxCUI'). It distinguishes itself from siblings by framing it as the prerequisite ID-lookup step for other tools, and explicitly lists supported types (company, drug).

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 instructs to 'Use FIRST whenever you have a name but need an ID', which is a clear when-to-use. However, it does not mention when not to use it or directly contrast with alternatives like 'entity_profile' or 'compare_entities', so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds behavioral context beyond annotations by revealing that the tool internally calls ai_visibility_check per entity and returns a ranked list with score, confidence, and signal density. No contradiction exists.

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

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

The description is three sentences, front-loaded with the core purpose. The second sentence explains the mechanism and output; the third provides a use case. Every sentence earns its place, with no redundant or vague wording.

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 4 params and no output schema, the description provides a complete picture: purpose, use case, implementation (delegation to ai_visibility_check), and output format (ranked list with score, confidence, signal density). Coupled with the fully described schema and clear annotations, an agent has all necessary context to select and invoke the tool correctly.

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

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

Input schema has 100% parameter coverage, with each parameter described in detail (including the first-entity-as-subject rule and the _apiKey prerequisite for the 'anthropic' model). The description reinforces the entity-comparison concept but adds little new parameter-level meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description opens with a specific action ('Compare AI visibility across multiple entities side-by-side') and clearly explains the mechanism: probes each entity with ai_visibility_check, ranks by score, and highlights most/least recognized. This distinguishes it from sibling tools like ai_visibility_check (single entity probe) and compare_entities (generic comparison).

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 the tool is 'Useful for competitive AI-marketing audits' and gives a concrete example ('does Claude know about us as well as our competitors?'). While it does not explicitly name when not to use it, the multi-entity focus and reference to ai_visibility_check imply the appropriate context 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 read-only, open-world, idempotent, non-destructive. The description adds crucial behavior: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts while the rest still returns. This goes well 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?

Every sentence earns its place: fan-out sources, use cases, return breakdown, ecosystem boundary, and failure handling. It is front-loaded with the composite one-call value proposition and remains readable despite the length.

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

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

With no output schema, the description thoroughly lists the summary block fields, per-advisory detail, links, and recent alternative versions. It also covers ecosystem scope and graceful degradation, making the tool fully understandable for invocation.

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

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

Input schema already provides 100% coverage, describing package as an npm package name (scoped accepted) and version with default behavior. The description adds no additional parameter semantics beyond what the schema states; baseline 3 is appropriate.

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

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

The description uses a specific verb+resource: composite check for npm package vetting, naming deps.dev and bundlephobia. It distinguishes from sibling tools by its one-call aggregation and focus on 'should I add this package' decisions.

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 agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. It also gives exclusions: NPM ecosystem only in v1, and directs PyPI/Maven/Cargo/Go to 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 safety traits, and the description adds deep behavioral detail: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagged, and output format (offsets + similarity scores). This goes well beyond the annotations and alerts the agent to limits and side effects. 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 compact, front-loaded with the core purpose, and every sentence earns its place: use case, workflow, and technical details are packed into two sentences with no redundancy.

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

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

For a 3-param tool with no output schema, the description covers the return format, preprocessing behavior, input limits, and usage context. Combined with rich annotations, the agent has a complete picture of when and how to invoke it.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces parameter meaning (e.g., 'text you already pulled', query examples) but adds little beyond the schema's detailed property descriptions. It does not introduce syntax or constraints not already in 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 'Semantic search INSIDE a fetched record' – a specific verb, resource, and scope. It clearly distinguishes itself from sibling tools by naming ask_pipeworx_grounded and contrasting whole-document grounding with passage-level search.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt' and provides a workflow pairing with ask_pipeworx_grounded. This gives clear context and names an alternative, satisfying the 'when/when-not/alternatives' 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?

It discloses important behavioral details: the need for a Pipeworx OAuth account for persistence, the return of the subscription ID, SMS verification and 10/day cap, and the feed delivery model. These go beyond the annotations and add genuine context. 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 moderately long but well-structured with clear use of colons and examples. Each sentence adds substantive information about types, delivery, and requirements, with minimal 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 3 params, nested objects, and multiple types, the description covers auth, return value, type semantics, and delivery constraints. It omits webhook (covered in schema) and doesn't describe output beyond the ID, but given the lack of an output schema, this is quite 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?

Although schema coverage is 100% and includes examples, the description adds interpretive value such as 'items:["5.02"] = officer change' and explains the meaning of types like polymarket_edge and fred_series, enhancing understanding beyond the raw 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 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource. It also mentions the return of the subscription ID, and the variety of supported subscription types distinguishes it from siblings like list_subscriptions and unsubscribe.

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 by noting the OAuth requirement, supported types, delivery options, and the always-on feed with pull mechanisms. It doesn't explicitly name alternative tools or exclusions, but the purpose statement itself implies when to use this tool.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. The description adds that results are drawn from a live catalog of thousands of tools, and describes the call behavior for no args vs topic. This exceeds the annotation baseline 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 dense but well-structured, with a leading set of example questions, a clear return description, and a one-sentence usage directive. Every sentence carries informational weight 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?

For a tool with no output schema, the description fully explains the return payload (category-bucketed questions with tool+argument shapes) and the parameter behavior. It also contextualizes its place among sibling meta-tools, making it a complete onboarding reference.

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 the `topic` parameter at 100% with an enumerated list of focus areas. The description reinforces this with examples like 'finance' and 'pharma' and clarifies the default 'cross-category spread' behavior. Since the schema already documents the parameter, the description adds practical context rather than repeating syntax.

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 the tool returns category-bucketed example questions with exact tool+argument shapes, positioning it as the onboarding entry point. It distinguishes itself from siblings by framing queries like 'what can I ask' and explicitly listing use cases. This is a specific verb+resource with clear scope.

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

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

Explicitly instructs to use this FIRST when unfamiliar with Pipeworx capabilities, and to learn how to call meta-tools. It also notes that omitting `topic` yields full spread while passing a topic focuses the results. This is clear when-to-use guidance with a nod 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?

The description adds valuable behavioral context beyond annotations: ownership enforcement ('you can only cancel your own subscriptions') and the soft-delete behavior ('deactivated, not deleted') with its effect on recent_alerts. These details clarify the tool's impact and are not redundant with 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 two sentences, front-loaded with the primary action, then the ownership constraint, and finally the consequence. Every word contributes meaning, with no filler or redundancy.

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

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

For a single-parameter tool with no output schema, the description covers the essential aspects: what it does, who can use it, and the data impact. It also ties to sibling tool recent_alerts, providing a complete picture for the agent.

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

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

The input schema already documents the id parameter with 100% coverage, providing a baseline of 3. The description adds the crucial ownership constraint (the id must belong to the caller), which gives extra semantic meaning beyond the schema's basic type/format description.

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

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

The description clearly states the action: 'Cancel a subscription by id.' It specifies the resource (subscription) and the operation (cancel), and differentiates from siblings like subscribe and list_subscriptions by describing the cancellation semantics and ownership constraint.

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 usage context is clear: it is for canceling a subscription, with the constraint that only the owner's subscriptions can be canceled. It does not explicitly mention alternatives or when not to use it, but the ownership and soft-delete behavior provide sufficient guidance for appropriate use.

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

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

Annotations already establish that the tool is read-only, idempotent, and non-destructive. The description adds meaningful behavior beyond this: the SEC EDGAR fast path, grounded-pipeline fallback, verbatim evidence with pipeworx:// citation, and a full verdict taxonomy. No contradiction with annotations exists.

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

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

The description is dense but each sentence earns its place: trigger phrases, usage rule, routing logic, output contract, and efficiency benefit. It is front-loaded with immediately recognizable patterns and has no filler or irrelevant 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?

With no output schema present, the description fully compensates by enumerating the returned verdicts, the value plus citation, and reasoning. It also covers both the structured and grounded paths, making the tool's complete behavior understandable without further lookup.

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

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

Although the schema covers 100% of parameters, the description enriches both. It explains that tolerance_pct overrides the claim's implied tolerance, recommends 1-2 for hallucination detection, and documents the default cap of 5. Concrete claim examples also clarify the claim parameter beyond the schema's generic description.

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

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

The description clearly defines the tool as natural-language claim verification against authoritative sources, with explicit trigger phrases like 'fact check' and 'verify the claim that'. It distinguishes itself from sibling research and Q&A tools by its specific verdict-based output and routing 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?

It states a clear when-to-use rule: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also divides claim types (company-financial vs any other) into two paths. It does not explicitly name alternative sibling tools to avoid, 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.