Mailchimp

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds beyond annotations by detailing return structure (per-model {score, confidence, signals, raw_response} + combined view) and cost implications (free Workers AI, BYO key for Anthropic). No contradictions.

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

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

The description is concise, with three sentences covering action, details, and usage. It is front-loaded with the core action and efficiently provides necessary information without redundancy.

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

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

Given the tool has 4 parameters, no output schema, and moderate complexity, the description is complete. It explains input parameters, output structure, and use cases. The absence of output schema is mitigated by the explicit return format description.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining default behavior for models (free Workers AI), the role of _apiKey (required for Anthropic with BYO key), and the purpose of context (disambiguation). This elevates the score 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 clearly states the tool's purpose: probing LLMs for knowledge about a business/brand/product/topic and scoring visibility 0-100 per model. It uses a specific verb-resource pair and distinguishes itself from sibling tools focused on general Q&A or research.

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 mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also explains when to use the optional parameters (models, _apiKey). However, it does not explicitly state when not to use this tool vs. sibling tools.

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

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

Annotations already declare readOnly/idempotent, and the description adds meaningful context: it routes across thousands of tools, fills arguments, returns citation URIs, works on all tiers, and is 'one fast call'. It does not mention error behavior or rate limits, but annotations cover safety.

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?

Long but well-structured: starts with preference, then mechanism, then use cases/examples, then alternatives. Every sentence adds value; the list of examples is practical. Slightly dense but not bloated.

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-required-param tool with no output schema, the description completely explains what it does, when to use it, how it differs from siblings, and what the return includes (structured answer with citations). It also notes tier compatibility and speed.

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

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

Schema covers 100% of params with descriptions and aliases. Description adds value by providing example question types ('what is', 'look up', 'find', 'get the latest') and concrete examples ('current US unemployment rate', 'Apple's latest 10-K'), helping agents formulate correct questions.

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 uses specific verbs and resources: 'routes the question to the right one of 5,562 tools across 1,462 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It clearly distinguishes from siblings by naming ask_pipeworx_grounded and deep_research as alternatives.

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 provides when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and step-up conditions for alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'. Also covers breaking news handling.

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

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

The description adds substantial context beyond the annotations: it explains the live-testing behavior, that current behavior matches the stable version, that results feed into merge decisions, and that this is a fully functional router despite being experimental. It also confirms the response shape matches ask_pipeworx, leaving no ambiguity about side effects.

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

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

The description is a single dense paragraph with three sentences, each conveying essential information: beta attribution, current status, usage instruction, and fallback guarantee. Minor redundancy exists (e.g., 'identical' and 'matches exactly' overlap), but it remains efficient and front-loaded.

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

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

Given the tool's complexity (a router over thousands of tools) and the absence of an output schema, the description sufficiently covers versioning, behavioral differences, usage, and safety. It does not elaborate on the routing mechanics, but that is likely unnecessary 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?

Schema coverage is 100%, with all parameters (aliases and question) well described. The description adds no parameter-specific detail, but the schema already fully documents the 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 identifies this as a beta variant of ask_pipeworx, functioning as a universal router over the same 5,562 tools. It explicitly differentiates from the stable sibling by noting candidate routing improvements and live testing, 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?

It provides an explicit usage directive: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also contrasts with the stable router and clarifies that no candidate is active currently. However, it does not explicitly state when NOT to use it (e.g., for stable/production needs), though this 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds significant behavioral context beyond annotations: refusal reasons with possible values, exact output shape (answer, evidence, confidence, source, fetched_at, refusal_reason), explicit refusal behavior when data doesn't answer, and the internal routing across 5,562 tools. It also discloses the extra LLM call cost, which is not inferable from annotations or schema.

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

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

The description is dense but every sentence contributes: purpose, mechanism, return contract, usage scenario, and cost tradeoff. It is front-loaded with the most important qualifier ('Hallucination-resistant answer mode') and avoids redundancy. The structure flows logically from what → how → when → tradeoff, with 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?

There is no output schema, so the description carries the burden of explaining return values, and it does so explicitly with both success and refusal structures. Combined with annotations (readOnly, openWorld, idempotent) and the sibling context (ask_pipeworx), the agent has complete information for invocation and result interpretation. High complexity is fully addressed.

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: all 6 parameters are aliases for the same question field, each with a description. The tool description itself adds no parameter-level detail beyond what the schema provides, but since the schema fully explains the parameter, the baseline of 3 is appropriate. The description doesn't hurt, but it doesn't elevate semantics either.

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, non-generic purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly states the mechanism (extracting answers using only tool results) and distinguishes it from the sibling ask_pipeworx by name, emphasizing the grounded extraction behavior. The verb+resource framing is precise.

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 provides when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' and when not: 'prefer ask_pipeworx for casual lookups.' It names the alternative (ask_pipeworx) and gives a cost-based tradeoff (one extra LLM call), offering clear decision guidance.

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

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

The description goes far beyond the annotations (readOnlyHint, idempotentHint) by detailing resolution matching, parent event extraction, news fallback mechanisms, safety short-circuits, cancellation rule parsing, and response shape. No contradiction with annotations; all behavioral traits are consistent and well-explained.

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 thorough but lengthy; however, it is front-loaded with the primary purpose and structured with clear sections (use cases, classifiers, fan-out examples, response shapes, safety). Every sentence adds necessary detail for a complex tool, making it appropriate rather than overly verbose.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure including market match confidence, parent event extraction, news fields, and safety behaviors. It addresses edge cases (low confidence, closed markets, wide spreads) and provides actionable guidance for agents, making it highly 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?

With 100% schema coverage, the description adds significant value by providing concrete examples for the 'market' parameter (slug, URL, text), explaining the 'depth' parameter's enum values and defaults, and clarifying the 'include_raw' parameter's effect on response size. This enriches meaning beyond the schema.

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

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

The description clearly states the tool researches Polymarket bets using Pipeworx data, with specific verb 'Research', resource 'Polymarket bet', and concrete examples like slug, URL, or question text. It effectively distinguishes from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on data research and evidence gathering.

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

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

The description explicitly states when to use the tool ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and includes context about behavior for low-confidence matches, closed markets, and wide spreads. However, it lacks explicit when-not-to-use or direct comparisons to sibling tools, though the use cases are well 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?

Annotations already declare the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds value by specifying data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), off-calendar fiscal year handling, result sorting by primary metric, and inclusion of pipeworx:// citation URIs.

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 five sentences, front-loaded with example queries and a clear directive. Every sentence adds value: usage examples, data source details, sorting behavior, and alternative comparison. 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?

With no output schema, the description covers what data is returned per type and mentions citation URIs. It also notes that results are sorted and that the tool replaces many sequential lookups. The description is mostly complete for a two-parameter tool with full schema coverage, though it could optionally detail the exact output structure.

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 each parameter: for 'type', it explains what data is pulled per entity type (e.g., 'latest 10-K revenue + net income + cash + long-term debt' for company); for 'values', it clarifies required format (tickers/CIKs for company, drug names) and provides examples. This is significant added meaning 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's purpose: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It specifies the verb 'compare' and the resources (companies or drugs), and distinguishes from sibling tools like entity_profile which focus on single entities.

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

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

The description explicitly advises 'ALWAYS PREFER over sequential single-pack lookups' and provides example queries like 'which is bigger', indicating when to use this tool. It partially addresses when not to use by contrasting with sequential lookups, but does not explicitly name alternatives like entity_profile.

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?

Besides the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses extensive behavioral traits: decomposition into facets, parallel routing to 5,562 tools, return packet structure (evidence + confidence + source + fetched_at + citation), explicit gaps[] for unanswerable facets, contradictions[] for standard/thorough, citation fetchability guarantees, semantic excerpting, and timing expectations. This goes far beyond what annotations provide.

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

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

The description is long but well-structured and front-loaded with critical information (account requirement, NOT open-web search). Each sentence packs useful details, though some redundancy exists (e.g., citation details repeated in the findings packet and later for citation_uri). It earns its length with high information density, but could be slightly trimmed without losing value.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It covers return values (findings packet, gaps[], contradictions[], hop field, citation_uri), error/limitation behavior (empty gaps for non-catalog topics), authentication/plan constraints, performance expectations, and comparison to alternatives. Everything an agent needs to invoke correctly and interpret results is present.

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

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

Schema description coverage is 100%, so the schema already documents both parameters in detail (depth enum with explanations, question parameter). The description adds extra semantics beyond the schema, such as the paid plan requirement for 'thorough', expected latency ranges, and how depth affects gap recovery and contradiction scans. This adds value beyond the baseline 3, but the schema already carries substantial semantic weight.

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: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources... in ONE call.' It uses a specific verb (research) and resource (structured data sources), and explicitly distinguishes it from open-web search and the sibling tool ask_pipeworx, 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 gives explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data... For a single lookup use ask_pipeworx... For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also notes the account requirement and alternative if not signed in, covering exclusions and alternatives thoroughly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is clear. The description adds behavioral transparency by stating that results are 'ready to call directly, no second schema lookup needed,' which is useful context 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 concise yet comprehensive, fitting all essential information in a single paragraph. It front-loads the purpose, then covers usage, return value, and a call-to-action. Every sentence adds 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?

Given that there is no output schema, the description adequately explains that the tool returns 'top-N most relevant tools with names, descriptions, and full input schemas.' This covers the key output. It could mention pagination or error handling, but for a discovery tool this is 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 all 6 parameters described. The description adds value by explaining the aliases (task, q, search, description) and providing concrete examples (e.g., 'analyze housing market trends'). This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many domains (SEC filings, FDA drugs, etc.) and explicitly distinguishes it from siblings by advising 'Call this FIRST when you have many tools available.' This makes the purpose specific and differentiated.

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

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

The description provides clear when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available.' It implicitly suggests using this tool before using other tools, but does not explicitly state when not to use it (e.g., if the agent already knows the exact 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, non-destructive behavior. The description adds valuable context: fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), notes the USPTO PatentsView API sunset May 2025 and soft-fail behavior, and specifies that names are not supported. No contradiction with annotations.

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

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

The description is front-loaded with examples and concise use-cases, but it is somewhat long (multiple sentences). It earns its place with dense, actionable information. Minor redundancy could be trimmed.

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

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

With no output schema, the description compensates by listing return data (CIK, filings, fundamentals, etc.). It covers key behavioral details and limitations (patents soft-fail, name unsupported). Missing explicit error/rate limit info, but overall complete for the complexity.

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

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

Schema coverage is 100% with descriptions for all 2 parameters. The description reinforces that value accepts ticker or CIK (not names) and adds context for the type parameter (only 'company' supported). This adds marginal value beyond the schema.

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

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

The description uses clear examples ('Tell me about X', 'research Acme') and explicitly states it provides a 'full cross-source profile of a US public company in one parallel call'. It lists the returned data categories, differentiating it from siblings like resolve_entity and compare_entities.

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

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

The description explicitly advises 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views and directs users to use resolve_entity if only a name is available, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already mark destructiveHint=true and idempotentHint=true. Description adds context about clearing stale or sensitive data, which is helpful but not essential beyond annotations.

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

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

Two sentences, no redundancy, front-loaded with the action. Every word serves a purpose.

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 tool with one parameter and no output schema, the description fully covers purpose, usage, and consequence (deletion). No 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?

Input schema covers the single 'key' parameter with a description. The tool description does not add new semantics beyond mentioning 'by key', so baseline score of 3 is appropriate.

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

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

Clearly states 'Delete a previously stored memory by key.' Verb and resource are specific, and it distinguishes from siblings like 'remember' and 'recall'.

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 provides when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also mentions pairing with 'remember' and 'recall' to indicate alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, indicating a safe read operation. The description adds specific steps ('Fetches the page, extracts title/description/key links, emits standard llms.txt markdown'), which enriches understanding. It lacks details on edge cases like timeouts or large pages, but the annotations cover safety well.

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 (three sentences) and front-loaded with the main action. Every sentence adds value—purpose, behavior, and use cases—without any 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?

With only two parameters and no output schema, the description covers purpose, behavior, and use cases thoroughly. Annotations provide safety context. It is nearly complete for an agent to use correctly, though it could mention that the output is a single text blob (already stated) and perhaps a note on limitations (e.g., only works for public URLs).

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 both parameters (url and max_links), so the schema itself is informative. The description adds no additional meaning beyond summarizing the output format, meeting the baseline but not exceeding 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 clearly states the verb 'generate' and the specific resource 'llms.txt file', making the tool's purpose unmistakable. It also lists concrete use cases (getting a client's site indexed, drafting for own project, auditing competitors), which distinguishes it from any sibling tool even without explicit differentiation.

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

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

The description explicitly provides usage scenarios ('Useful for: getting a client's site indexed...'), helping the agent decide when to invoke it. However, it does not mention when NOT to use it or suggest alternative tools, missing an opportunity for clearer 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 indicate read-only, idempotent, non-destructive behavior. Description adds that only active subscriptions are returned by default, and mentions the include_inactive parameter aligns with schema.

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

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

Two sentences, efficient and front-loaded with action and returned fields. No unnecessary words.

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

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

For a simple list tool with one optional parameter, description covers purpose, return fields, and usage context. Output schema not provided but return fields are listed.

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 description for include_inactive. Description implies active-only by default, but adds no new parameter details beyond 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 lists the caller's active subscriptions and specifies return fields. Distinguishes from sibling tools like subscribe/unsubscribe by focusing on listing existing subscriptions.

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

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

Explicitly tells when to use: to review monitoring before adding more or to find an ID to cancel. This provides context alongside sibling tools for subscription management.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds value by specifying the return fields (name, member count, engagement metrics, configuration) and providing an example ID format, enhancing transparency 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 two sentences, front-loading the purpose and essential info. No unnecessary words; every sentence adds value.

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

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

Given the presence of an output schema and complete annotation coverage, the description sufficiently covers what the tool does, what parameters are needed, and the nature of returned data. No 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?

Schema description coverage is 100%, so each parameter is already described in the schema. The description adds minimal new info (only an example ID value), so it meets the baseline without significant enhancement.

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 'Get' and identifies the resource as 'detailed settings and stats for a specific audience'. It clearly distinguishes from sibling tools like mailchimp_list_audiences (which lists) and mailchimp_get_campaign (different resource).

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 does not explicitly state when to use this tool over alternatives. It implies usage for retrieving a single audience's details, but lacks direct comparison with sibling tools. There is no 'use this when...' or 'instead of...' guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds value by stating what data is returned (settings, tracking, performance stats, send history). No contradiction, but does not elaborate on required permissions or rate limits.

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

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

Single sentence, front-loaded with verb and resource, listing return categories. 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?

Output schema exists (indicated true) so description is not required to explain return values. It lists high-level return categories, adequate for a retrieval tool. No missing 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%, so baseline is 3. Description provides an example ID format 'abc123def456' matching the campaign_id parameter, but adds no additional semantic or formatting guidance 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 verb 'Get', the resource 'campaign', and the method 'by ID'. It lists the categories of returned data (settings, tracking, performance stats, send history), distinguishing it from sibling tools like mailchimp_list_campaigns which lists campaigns.

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?

Implicitly suggests use when details of a specific campaign are needed, but no explicit when-not or alternatives are mentioned. Sibling names indicate there is a list tool, but the description does not guide the agent to choose between list and get.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds that it returns audience names, member counts, and engagement stats, providing useful behavioral context 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?

Two sentences, front-loaded with the action, no extraneous content. Efficient and clear.

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?

Output schema exists, so description doesn't need to detail returns beyond mentioning what stats are included. Sibling differentiation present. Could add pagination hints but schema covers it. Nearly 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 covers 100% of parameters with descriptions. The tool description adds no additional parameter-level information, so baseline score of 3 applies.

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

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

Description clearly states it views all audiences, with verb 'view' and resource 'audiences'. It distinguishes from sibling mailchimp_get_audience by directing to that tool for detailed settings.

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 mentions alternative mailchimp_get_audience for detailed settings, giving clear context for when to use this tool. Does not mention other siblings, but the purpose is focused enough.

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 as true, so safety profile is clear. The description adds that it returns a list with specific fields, which is useful but does not mention pagination or auth behavior beyond the schema. Given annotations cover the main traits, a score of 3 is appropriate.

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 with no wasted words. Front-loaded with the core action and result. Every sentence adds value.

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

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

An output schema exists, and the description covers key return fields (title, type, status, send timestamps). However, it suggests 'all' campaigns despite pagination via count/offset, which is a minor omission. Overall sufficient for a list tool with good annotations.

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

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

Schema description coverage is 100%, so the schema already documents all parameter details. The description does not add additional parameter-level information beyond what is in the schema, so the baseline score of 3 applies.

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

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

The description uses a specific verb ('View') and identifies the resource ('all email campaigns'). It details what is returned (title, type, status, send timestamps) and explicitly distinguishes from the sibling tool 'mailchimp_get_campaign' for full details.

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

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

The description clearly states when to use this tool ('View all email campaigns') and provides an explicit alternative ('Use mailchimp_get_campaign for full details'). This gives the agent precise guidance on tool selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destructive behavior. The description adds that it returns email, status, and merge fields but does not disclose additional behavioral traits like pagination details, rate limits, or authentication specifics beyond the API key. It is adequate given 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 concise, using a single sentence with an embedded example. It is front-loaded with the verb and resource. No wasted words, but a second sentence could improve completeness without sacrificing brevity.

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 rich annotations, 100% schema coverage, and existence of an output schema, the description adequately covers the core purpose and return values. It does not describe pagination or filtering in text, but those are in the schema. The tool is simple enough that the description feels complete for most use cases.

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

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

Schema description coverage is 100%, so baseline is 3. The description reinforces the list_id parameter with an example but does not add new semantic meaning beyond the schema. The mention of return values is about output, not input parameters.

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

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

The description clearly states the verb 'Get' and resource 'subscribers in an audience', provides an example ID, and specifies the returned data (email, status, merge fields). It effectively distinguishes the tool from siblings like mailchimp_get_audience and mailchimp_list_audiences.

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 does not provide any guidance on when to use this tool versus alternatives (e.g., mailchimp_get_audience for a single audience, or mailchimp_list_audiences for listing all audiences). There is no mention of prerequisites, context, or 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 only mark readOnly=false etc., but the description adds significant behavioral context: anonymous filing returns a claim_token, later lookup behavior, rate limit of 5 per identifier per day, daily digest review, and that it is free and does not count against quota. 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?

Longer than the minimum, but every sentence contributes operational nuance (rate limits, token flow, MCP-server exclusion). The purpose is front-loaded and the prose is well-organized. Could be trimmed slightly but the length is justified by the tool's complexity.

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

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

Despite no output schema, the description fully covers submission types, exclusions, anonymous token retrieval, rate limits, and team-read cadence. An agent has everything needed to select and correctly invoke this tool versus alternatives.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value for the `message` parameter by instructing users to describe issues in Pipeworx tool terms and avoid pasting end-user prompts, and clarifies that claim_token is used alone. This goes beyond the schema, earning a 4.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates feedback types (bug, feature/data_gap, praise) and explicitly scopes the tool to Pipeworx-served tools, distinguishing it from sibling research/agent 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?

Provides explicit when-to-use triggers (wrong/stale data, missing tool, praise), a clear when-NOT-to-use exclusion (tools from other MCP servers should be filed there), and operational guidance for using claim_token later. This is textbook usage guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h). 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?

Two sentences plus a bullet list, front-loaded with purpose, every sentence adds value, 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 one parameter and no output schema, the description covers purpose, returned data, windows, use cases, data source, and caching completely.

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 enum descriptions. Description adds context beyond schema: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.'

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?

Clearly states the tool returns 'top tools, top packs, and total call volume' over configurable windows, distinguishing it from sibling tools like discover_tools or search 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?

Provides three explicit use cases (discovering hot sources, confirming canonical choices, aligning with agent needs) and mentions caching, but does not explicitly state when not to use or list 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, and non-destructive nature. The description adds extensive behavioral context: monotonicity checks, Jaccard similarity threshold, partition filter, fill check with book depth, and details on response structure. 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 somewhat verbose but every sentence adds value. It is front-loaded with the core purpose. Could be slightly more structured but remains efficient given the amount of information conveyed.

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 fully explains the return values for all modes, including fill check details and custom sizing. Covers all necessary behavioral and response context for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, but the tool description adds significant meaning by explaining that 'event' expects a Polymarket event slug and 'topic' a seed question, with concrete examples and how each mode works. Goes well beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three distinct modes of operation (no args, event, topic) with specific verbs and 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?

Provides explicit guidance on when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. Mentions an alternative tool (polymarket_fill_risk) for custom sizing, but lacks a comprehensive when-not-to-use 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?

The description provides extensive behavioral details beyond annotations, including model families, response structure, caching, and diagnostics. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, and the description adds rich context 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 verbose but every sentence adds value. It front-loads the purpose and then details models, response, and knobs. While slightly long, it is well-structured 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?

Given 9 parameters and no output schema, the description fully explains the response structure (by_segment, diagnostics, edge_pp_net, etc.) and cache behavior, making the tool's behavior completely clear for an AI 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?

All 9 parameters have descriptions that add meaning beyond the schema, such as explaining slippage_pp with context about Polymarket fees, and min_kelly with reasoning about skipping small opportunities. Schema coverage is 100%, and the description enhances each parameter.

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

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

The description clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It uses specific verbs and resources, distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description explicitly states it is for 'what should I bet on today' and helps agents discover opportunities without paging hundreds of markets. It also explains the tradeable-edge knobs for filtering. However, it does not explicitly state when not to use it or contrast with 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 indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds useful behavioral context: it reads snapshots, may have data gaps, and notes the 60-day TTL. 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 dense but well-structured: purpose first, then input parameters, then detailed response format in uppercase sections. Each sentence adds value, though the response section could be slightly more 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?

Despite no output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) and limitations (60-day TTL, no intraday). This is complete for a telemetry tool with multiple output 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?

Schema coverage is 100% with descriptions for both parameters. The description adds context beyond schema: bounds for 'days' (max 30, TTL limit), and explains that 'window' selects the snapshot family. Minor inconsistency in default/clamp values but overall adds value.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots, answering a specific question about edge longevity. It distinguishes itself from sibling tools like 'polymarket_edges' by focusing on historical trends rather than current edges.

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

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

The description explains when to use this tool (to assess how long an edge has existed and if it is shrinking) and implies when not to (if only current edges are needed, use 'polymarket_edges'). However, it does not explicitly list alternative tools or 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 indicate read-only, idempotent, non-destructive. The description adds behavioral details: walks the order-book ladder, returns verdicts (clean|degraded|cannot_fill), per-leg fill details, and risks like thin_legs and forced_directional_risk. No contradictions.

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

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

The description is dense and well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET). However, it is somewhat lengthy (over 200 words). Every sentence adds value, so it's concise in content but could be 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 complexity (two modes, no output schema), the description covers all important aspects: return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), verdicts, risk factors (thin legs, forced directional risk), and usage boundary conditions (size clamp 10–1,000,000). It 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%, but the description adds significant context: explains default side logic for baskets, clarifies size_usd semantics for each mode (spend vs proceeds vs settlement notional), and describes the interaction between parameters (e.g., single-market vs basket).

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and references sibling tools (polymarket_arbitrage, polymarket_edges) to differentiate usage.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns against not using it: 'partial basket fills convert an arb into an unhedged directional position (the dominant loss mode).'

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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details: safety fields (compatibility_warning, temporal_alignment, skipped counters), modes, response format. It does not contradict annotations and provides rich context beyond structured fields.

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

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

The description is front-loaded with the core purpose and well-structured with sections (Modes, Response, Safety Fields). However, it is slightly verbose, repeating some concepts like compatibility_warning causes. A more concise presentation would improve efficiency.

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

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

Given no output schema and 3 parameters with no required ones, the description thoroughly explains response structure (leg-by-leg prices, top_spreads_pp, safety fields) and covers all modes and edge cases. Temporal alignment and skipped counters are detailed, making the tool fully understandable without additional docs.

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

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

Schema description coverage is 100%. The description adds meaning beyond schema: explains that topic parameter offers 10 pre-mapped shortcuts with examples, and explicit parameters override the topic-mapped side. It clarifies the relationship between parameters and modes, which is not evident from schema alone.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. The verb 'compute' is implied and the resource 'spread' is specific. It distinguishes from siblings like polymarket_arbitrage by focusing on same-question cross-venue 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 provides two modes (topic shortcuts vs explicit ticker/slug) and explains when each is appropriate. It warns that most pre-mapped topics return compatibility_warning, guiding users not to rely solely on shortcuts. It lacks a direct 'use when not use' but the safety fields effectively define invalid cases.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds critical behavioral context: scoping (anonymous IP, BYO key hash, account ID) and that omitting the key lists all keys. No contradictions with annotations.

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

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

The description is highly concise: two sentences covering core function, use cases, scoping, and pairing. Every sentence adds value, front-loading the most important information (retrieve/list) first. No unnecessary words.

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

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

For a simple tool with one optional parameter and no output schema, the description covers all essential aspects: function, usage examples, scoping, and relationship to sibling tools. It does not describe the return format (e.g., a string value or list of keys), but given the tool's simplicity, this is a minor omission.

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 description repeats the schema's parameter description ('omit the key argument to list all keys') without adding new meaning. Schema coverage is 100%, so the baseline of 3 applies; no extra parameter semantics are provided beyond what the schema already offers.

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

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

The description clearly states the tool's dual function: retrieving a stored value by key or listing all keys when no key is provided. It gives concrete examples of use (ticker, address, research notes) and distinguishes itself from the sibling tools 'remember' and 'forget' through pairing guidance.

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

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

The description provides clear usage context: 'look up context the agent stored earlier...without re-deriving from scratch.' It implies when to use (retrieval) and pairs with alternatives (remember/forget). However, it does not explicitly specify when not to use this tool versus other lookup tools or exclude any scenarios.

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

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

Description adds behavioral context beyond annotations: it's a read operation (consistent with readOnlyHint), explains that mark_read changes state but is non-destructive (consistent with destructiveHint=false), and notes idempotency when not using mark_read. No contradictions with annotations.

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

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

Description is a single paragraph of moderate length, front-loaded with purpose. All sentences add value, though it could be slightly more compact without losing clarity. No fluff.

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

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

Despite no output schema, description mentions return fields (source, citation_uri, raw payload). Covers all 5 parameters, explains polling behavior, and provides a fallback URL. Complete for a retrieval tool.

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

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

Schema coverage is 100%, but description adds meaning: explains 'type' as subscription type (examples like 'sec_8k'), 'since' as ISO timestamp, and describes the effect of 'mark_read' and 'unread_only'. Provides practical usage details beyond 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 'Pull fired events from your subscription feed' with specific verb and resource. It explains what the alerts contain (source, citation_uri, raw payload) and distinguishes from siblings by focusing on retrieval of recent alerts from a persisted feed.

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

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

Explicit guidance on filtering by type and since, using mark_read to manage read state, and noting that polling works fine. Also mentions an alternative URL for scripts/dashboards, aiding in tool selection.

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

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

Beyond annotations (readOnly, idempotent), the description discloses the parallel fan-out to multiple sources, fallback mechanism, soft-failure of the patents API, and the output structure (changes[] grouped by source, total_changes count, citation URIs). No contradictions with annotations.

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

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

The description is well-structured with examples upfront, functional details, and a clear sibling differentiation at the end. While slightly long, every sentence adds value; could be marginally more concise but front-loads key information effectively.

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

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

Given the tool's complexity (multiple sources, fallback, input formats) and lack of output schema, the description thoroughly explains behavior, output structure, and constraints. Agent has enough context to use 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?

With 100% schema coverage, the description adds substantial value: examples for `since` (ISO date and relative shorthand like '30d'), explains that `value` accepts ticker or CIK, and notes that `type` only supports 'company'. Provides monitoring recommendation for `since`.

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 starts with example queries ('What's new with X', 'latest on Y') and explicitly states it's a change feed for a company in the last N days. It lists the exact sources (SEC EDGAR, GDELT→GNews, USPTO) and distinguishes itself from the sibling tool entity_profile, making the purpose crystal clear.

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

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

Provides explicit when-to-use scenarios (e.g., 'updates on Acme') and when-not-to-use (pointing to entity_profile for static profiles). Also explains fallback behavior (GDELT preferred, GNews when rate-limited) and gives parameter usage examples for `since` and `value`.

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

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

Adds behavioral context beyond annotations: scoping by identifier, persistence for authenticated users, 24-hour expiry for anonymous sessions. 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?

Four sentences, front-loaded with purpose, followed by usage, storage details, and pairing. Every sentence adds value with no fluff.

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

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

Fully explains the tool's operation, usage context, storage behavior, and complementary tools. No need for output schema given the simplicity.

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 has 100% coverage with descriptions for key and value. Description echoes the parameter purpose but does not add significant new meaning beyond the schema examples.

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 'Save data the agent will need to reuse later' with clear verb and resource, and distinguishes from sibling tools recall and forget by mentioning pairing.

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 ('when you discover something worth carrying forward... so you don't have to look it up again') and mentions pairing with recall/forget, but does not explicitly state when not to 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?

Beyond the readOnly/idempotent annotations, the description discloses valuable behavioral traits: it cascades through multiple lookup endpoints internally, degrades gracefully when LEI/FIGI sources are unavailable, and explicitly lists unresolved identifiers under `unresolved`. It also notes that every identifier is source-labelled, adding transparency about provenance. No contradiction with annotations.

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

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

The description is long but information-dense and well-structured. It front-loads with example queries and the core definition, then details each supported type. Some sections (e.g., the extended LEI/FIGI explanation) could be trimmed without losing essential guidance, but the length is justified by the tool's complexity.

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

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

Given the tool's complexity and lack of an output schema, the description is remarkably complete. It explains what identifiers are returned, the sources (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), fallback behavior, and even includes a specific citation URL for drug lookups. It fully covers the return value semantics an agent would need.

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?

Though the schema already covers 100% of parameters, the description adds substantial meaning. For `type`, it elaborates on company vs drug outputs including specific identifier types and source details. For `value`, it lists accepted formats (ticker, CIK, ISIN, brand/generic) and even explains how an ISIN resolves to a legal entity. This goes well beyond the schema's basic descriptions.

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

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

The description clearly defines the tool's purpose: resolving user-spoken names to canonical identifiers required by other tools. It opens with concrete example queries and explicitly lists supported types (company, drug) with specific outputs (CIK, LEI, FIGI, RxCUI). It distinguishes from siblings by stating 'Use FIRST whenever you have a name but need an ID' and noting it replaces 2-3 manual lookups.

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

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

The description provides explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains the two entity types and what each resolves, giving agents clear context for selecting this tool over alternatives. The phrase 'replaces 2-3 manual lookups' further reinforces its intended role in a workflow.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds that it internally calls ai_visibility_check and returns a ranked list, which is helpful but does not significantly extend 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?

Three sentences, each with distinct value: purpose, usage example, output description. No fluff. Front-loaded with the core function.

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

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

Given 4 parameters and no output schema, the description explains the output (ranked list with score, confidence, signal density), covers all parameter nuances, and provides a usage example. Sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions. The description adds key context: entities first entry is the subject, rest are competitors; models default to workers-ai; context disambiguates. This enriches 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 the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, and ranks them. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities.

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

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

The description explicitly targets competitive AI-marketing audits with an example question, implying when to use it. It does not explicitly state when not to use it or name alternatives, but the context makes it clear this is for multi-entity comparison.

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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral context: partial failures degrade gracefully, bundlephobia's first measurement may take 5-30s, and sources_failed will list timeout. This goes well 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 comprehensive and well-structured, starting with purpose, then usage, ecosystem limitation, and graceful degradation. Slightly verbose but every sentence adds value. Could be tightened while retaining clarity.

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

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

Given the lack of output schema, the description details the return information: summary fields, per-advisory detail, links, alternative versions. It also covers error behavior (timeout, sources_failed). This makes the tool fully self-contained and usable without 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 both parameters. The description adds further context: 'package' accepts scoped packages like @types/node, 'version' defaults to latest when omitted. It also previews return fields, which is helpful since there is 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 clearly states it is a 'composite should I add this npm package to my project check in ONE call' and specifies the sources (deps.dev, bundlephobia) and what it checks (license, advisories, version history, bundle size). This sets a clear and specific purpose that distinguishes it from sibling tools, which cover different domains.

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 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also notes ecosystem limitation: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', providing clear when-to-use and when-not-to guidance without naming alternative tools.

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

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

Annotations already declare safe read/idempotent behavior. Description adds technical details: embedding model (BGE-base-en), cosine similarity, 500-char windows, 200K char cap with truncation flag, and return of offsets and scores.

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?

Concise yet comprehensive. Four sentences: core function, usage, pairing, technical details. No wasted words, front-loaded with key purpose.

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

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

For a complex tool with no output schema, description covers behavior, use cases, return value (passages with offsets/scores), technical constraints, and pairing. Fully adequate for an agent to invoke correctly.

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

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

Schema coverage is 100%. Description adds value: explains 'text' as document text with max chars, 'query' as natural-language with examples, and 'limit' with range. Provides more context than schema alone.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with a specific verb ('search') and resource ('record'). It distinguishes from siblings like ask_pipeworx_grounded by explaining the pairing and different use case.

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

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

Explicitly tells when to use: 'when the record is too big to cram into the prompt' and mentions alternative 'ask_pipeworx_grounded' for grounding over passages. Provides clear context and pairs with another 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?

Beyond annotations (which indicate mutation and idempotency), the description discloses the OAuth requirement, delivery channel behaviors (phone verification, SMS cap, webhook auto-disable, signing), and return value. 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 well-structured with main purpose front-loaded, followed by details. It is slightly long but every sentence is necessary given the complexity of the tool. Could be more concise in places.

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

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

Despite no output schema, the description explains the return value (subscription id) and covers all parameters, constraints, and behavioral details. It is sufficient for an agent to use the tool correctly.

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

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

Schema coverage is 100%, but the description adds extensive value: detailed type-specific JSON examples for params field, delivery channel explanations with constraints, and verification steps. This goes far beyond 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 states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses a specific verb (create) and resource (subscription) and clearly distinguishes from siblings like unsubscribe and list_subscriptions.

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

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

The description specifies the prerequisite (Pipeworx OAuth account) and provides examples for when to use each subscription type. However, it does not explicitly state when not to use this tool or directly compare to alternative tools like recent_alerts.

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, openWorld, idempotent, and non-destructive. The description adds behavioral context: 'call with no arguments for the full spread, or pass topic to focus' and 'returns category-bucketed example questions... drawn from the live catalog.' No contradictions.

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

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

The description is front-loaded with the core purpose but includes several alternative phrasings. While thorough, it could be slightly more concise without losing meaning. Overall well-structured with no wasted sentences.

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

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

Despite lacking an output schema, the description fully explains what is returned (categorized example questions with tool signatures) and how to use the tool. It also orients the agent within the tool ecosystem, making it complete for an onboarding tool.

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

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

Schema coverage is 100% with a clear description. The description adds semantic nuance: 'Omit for a cross-category spread' and lists example topic values, reinforcing the single optional parameter's purpose.

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

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

The description clearly states the tool is an onboarding entry point for new agents, using multiple phrasings ('What can I ask Pipeworx?', 'getting started'). It specifies it returns category-bucketed example questions with tool+argument shapes, distinguishing it as a discovery tool separate from the meta-tools it 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?

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides guidance on calling with no arguments vs. topic focus. It also mentions sibling meta-tools (ask_pipeworx, entity_profile, compare_entities) as context for later 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?

Adds context beyond annotations: 'deactivated (not deleted)' and link to recent_alerts. Annotations provide idempotentHint, destructiveHint; description elaborates on 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?

Two efficient sentences, front-loaded with purpose. Every sentence adds value.

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

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

Covers purpose, ownership, side effect (deactivation), and data retention via recent_alerts. Adequate for low-complexity tool with one param.

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?

Single param 'id' described in schema with uuid type. Description adds 'returned by subscribe', linking to related tool. Schema coverage 100% so baseline 3; slight extra value.

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

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

Clear verb 'Cancel' + resource 'subscription by id'. Distinguishes from siblings like subscribe and list_subscriptions.

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

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

States when to use (cancel subscription) and ownership constraint ('you can only cancel your own subscriptions'). No explicit when-not-to-use or alternatives, but clear enough.

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, open-world, idempotent, and non-destructive. The description adds crucial failure semantics: 'could_not_verify means the check did not happen... must not be shown as one' and 'unsupported means we looked and cover no source for it.' It also discloses the dual pipeline behavior and return format, going well beyond the annotations.

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

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

The description is front-loaded with natural-language example triggers, then states purpose, usage, and key behavioral warnings. It's a bit long, but every sentence adds meaningful information for a complex tool. The structure is logical and scannable.

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

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

For a tool with only 2 parameters and no output schema, the description fully explains return values (verdict, actual value, reasoning, citation), error semantics, and the two processing paths. It also clarifies the scope of 'unsupported' and 'could_not_verify'. No gaps remain for an agent to invoke or interpret results.

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

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

Schema description coverage is 100% with detailed field descriptions for 'claim' and 'tolerance_pct'. The description mentions 'exact percent-delta math' and 'approximately_correct', which reinforces the tolerance semantics, but the schema already carries the parameter meaning. Thus 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 specific verbs like 'verify' and 'validate' with a clear resource ('claim') and method ('against authoritative sources'). It distinguishes from siblings by explaining it replaces 4–6 sequential calls and covers two distinct pipeline paths (SEC EDGAR for financial claims, grounded for anything else).

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' which clearly establishes when to invoke. It also explains the breakdown between financial and non-financial claims, though it does not discuss alternatives or exclusions relative to sibling tools.

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