Chargebee

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds value beyond annotations by specifying the default model (Workers AI Llama-3.3-70b free), optional Anthropic probing with BYO API key, and return structure (per-model {score, confidence, signals, raw_response} + combined view). No contradiction with annotations.

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

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

Three sentences, no wasted words. Purpose is front-loaded, followed by default behavior and return format. Every sentence adds essential information.

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

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

Given no output schema, the description briefly but adequately covers return format. All 4 parameters are documented with clear descriptions. The tool is simple and the description covers purpose, usage, parameters, and returns 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 description coverage is 100%, baseline 3. The description adds meaning by stating the default model for 'models' parameter and clarifying that '_apiKey' is needed for Anthropic. It also notes that 'context' helps disambiguate common names, going 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 verb+resource: 'Probe one or more LLMs for what they know... and score visibility'. It specifies the output (score 0-100 per model) and distinguishes from siblings like 'ask_pipeworx' or 'deep_research' by focusing on AI visibility auditing.

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: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It implies when to use but does not explicitly state when not to use or mention alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, setting the safety profile. The description adds valuable context: it routes to 5,635 tools across 1,477 sources, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and works on every tier. This goes beyond the annotations without contradicting them, but could mention rate limits or timing for full transparency.

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

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

The description is long but front-loaded with the critical directive 'PREFER OVER WEB SEARCH' and a clear statement of purpose. It includes examples and explicit routing, but is somewhat verbose. Every sentence adds value, though a more concise version could trim redundancy without losing meaning.

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

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

With no output schema, the description properly explains the return type ('structured answer with stable pipeworx:// citation URIs'). It covers alternatives, usage trigger phrases, examples, and even notes it works on every tier. The description is fully self-sufficient for a tool of this complexity.

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

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

The schema provides 100% coverage, fully documenting the 'question' parameter and its aliases (query, q, prompt, text, input) with a description and examples. The tool-level description adds no meaning beyond what the schema already states, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: routing factual questions to authoritative structured data sources (SEC filings, FDA data, etc.) and returning cited answers. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives, making selection 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 is explicit about when to use it: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Use whenever the user asks...'. It also provides clear guidance on when to step up to alternatives (hallucination-resistant single answer → ask_pipeworx_grounded; broad/multi-part → deep_research), so the agent knows exactly when to switch.

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, destructiveHint=false. The description adds valuable behavioral context beyond annotations: it explains the experimental nature, the live candidate routing improvements, the current inactive state, and that it falls back to nothing but is a full working router. This helps the agent understand the tool's reliability and purpose fully.

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 moderately concise, covering the core identity, current status, usage guidance, and fallback behavior in three sentences. It is front-loaded with the beta identity and status. Slightly verbose but each clause adds meaningful information; could be tightened but remains effective.

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 clarifies that the response shape is identical to ask_pipeworx, providing necessary context for an agent unfamiliar with the base tool. It also explains the experimental state and current equivalence to the stable version, making the tool's behavior fully predictable. Nothing critical is missing.

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

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

Schema coverage is 100%, with all six parameters being aliases for 'question'. The description does not add parameter-level detail, but the schema fully documents each alias and the required 'question' field. The baseline of 3 is appropriate since schema handles parameter semantics completely.

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 identifies the tool as a beta version of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It differentiates itself from the stable ask_pipeworx by noting candidate routing improvements and its experimental status, so an agent can distinguish it from siblings like ask_pipeworx_grounded.

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 it exactly like ask_pipeworx when you want the newest routing' and explains the evaluation context (results compared against stable router). It also notes that currently no candidate is active, making it identical to ask_pipeworx, which prevents misuse. It does not mention ask_pipeworx_grounded, but the primary alternative is clearly addressed.

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. The description adds valuable behavioral details beyond annotations: the exact return object with evidence and refusal_reason, and refusal modes. It also discloses the extra LLM call cost. No contradiction with annotations.

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

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

The description is long but information-dense, packing purpose, output format, usage guidance, and cost into a coherent flow. Front-loaded with the primary trait (hallucination-resistant) before diving into mechanics. Could be slightly tighter, but every sentence earns its place.

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

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

The description fully compensates for the lack of an output schema by specifying the exact return shape on success and all refusal cases. It also explains routing, extraction behavior, and cost, giving the agent everything it needs to invoke the tool correctly and handle responses.

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 clear alias documentation for 'question'. The description adds no additional parameter meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool extracts grounded answers from tool results, emphasizes hallucination-resistance, and explicitly differentiates from ask_pipeworx by adding extraction and refusal behavior. The verb 'extracts' + resource 'answer' is specific and unambiguous.

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

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

Explicitly states when to use (high-stakes reads, when answers will be quoted/cited/acted on, must not invent facts) and when not to (casual lookups), and names the alternative ask_pipeworx. It also gives a cost-based tradeoff (extra LLM call).

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description goes far beyond, detailing fan-out logic, resolver contract with match confidence and alternatives, parent event extraction, news fallback handling, safety short-circuits for low-confidence matches and closed markets, wide-spread handling, and resolution rule risk. 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 lengthy but well-structured with labeled sections (classifiers, fan-out examples, response shapes, resolver contract, etc.). Every part adds necessary detail for correct usage. Some redundancy or verbosity (e.g., repeating 'status:' explanations) could be trimmed, but overall it's effectively organized for a complex tool.

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

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

Given the tool's complexity (multiple classifiers, fan-out sources, resolver logic, safety paths), the description is exceptionally complete. It covers input formats, processing behavior, all output fields, edge cases (closed markets, low confidence, wide spreads, cancellation rules), and interpretation warnings. Lacking an output schema, the description compensates fully.

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 coverage is 100% with descriptions for all three parameters (market, depth, include_raw). The description adds further context: examples for market, clear explanation of depth options, and guidance on when to set include_raw=true (recompute deltas, cite observations, or post-process). This adds significant value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It provides specific use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), and the detailed behavior distinguishes it from sibling tools like polymarket_edges by covering comprehensive research with classifiers, fan-out, and evidence packets.

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 examples and mentions classifiers, but does not explicitly state when not to use this tool or compare it to alternatives like polymarket_edges or polymarket_arbitrage. The context implies its role as a comprehensive research tool, but explicit exclusions would strengthen clarity.

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 and destructiveHint, so the description's listing of returned fields (name, email, etc.) adds useful behavioral context beyond annotations. It does not contradict annotations.

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

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

Two crisp sentences: first states the action and resource, second enumerates return fields. 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?

With annotations covering safety, schema covering parameters, and an output schema presumably detailing return structure, the description succinctly captures the tool's purpose and output, leaving no critical gaps.

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

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

Schema coverage is 100% and each parameter has a description in the schema. The tool description does not add additional parameter-level meaning beyond what is already provided.

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

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

The description uses a specific verb ('Get') and resource ('complete customer profile') and distinguishes from sibling tools like chargebee_get_subscription and chargebee_list_customers by focusing on a single customer by ID.

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

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

The description implies usage when a customer ID is available and full profile is needed, but does not explicitly compare with siblings or state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value by detailing return content (plan, status, billing dates, etc.), going beyond the annotations. No contradictions.

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

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

Two sentences, front-loaded with purpose (first sentence) and content list (second). 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?

Given output schema exists and parameters are fully documented, the description covers needed context for a read-only detail tool. Annotations support this.

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 parameter descriptions. The description does not add further parameter meaning; it focuses on output. Baseline 3 is appropriate.

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

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

The description clearly states 'Get full subscription details by ID.' It specifies the resource (subscription) and action (get details), listing return content (plan, status, billing dates, customer info, charges). This distinguishes it from siblings like chargebee_list_subscriptions and chargebee_get_customer.

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

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

The description implies usage for individual subscription lookup by ID but lacks explicit guidance on when to use vs siblings like chargebee_list_subscriptions for listing. No when-not or alternative mentions.

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 the description adds value by specifying return fields and pagination behavior. It does not contradict annotations and provides useful context beyond the structured fields.

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

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

The description is a single concise sentence that front-loads the key purpose. It is not verbose, but could be slightly more structured (e.g., bullet points) without adding length. It earns its place with clear information.

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

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

Given the presence of annotations and a complete output schema, the description covers the essential points: listing with pagination and return fields. It is adequate for a simple list tool with good structured metadata, though it does not mention edge cases or error handling.

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

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

Schema description coverage is 100%, meaning all parameters have descriptions in the schema. The tool description adds no additional parameter context beyond what the schema already provides, so the 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?

The description clearly states the verb 'List', the resource 'customers', and includes pagination details. It also lists the return fields, distinguishing it from siblings like chargebee_get_customer (single customer) and other list tools.

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

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

The description implies when to use (to list customers) but provides no explicit guidance on when not to use or how it differs from siblings like chargebee_get_customer. The agent can infer from sibling names, but the description itself lacks direct alternative differentiation.

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 value by detailing pagination (limit and offset) and the returned fields, which are beyond the annotations. No contradictions.

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

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

Two concise sentences: first states purpose and filters, second states return fields and pagination. No wasted words, front-loaded with key information.

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

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

With output schema existing, the description covers all essential aspects: purpose, filters, pagination, and return fields. No missing elements given the tool's complexity and annotation richness.

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 parameters are well-documented. The description adds contextual grouping (filters vs pagination) and example values for status, but does not provide new semantic information 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 lists invoices with optional filtering by status and customer ID. It specifies returned fields (invoice numbers, amounts, dates, payment status), distinguishing it from sibling tools like chargebee_list_customers and chargebee_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 implies usage for listing invoices with filters, but lacks explicit guidance on when to use this tool versus alternatives (e.g., retrieving a single invoice or using other chargebee list tools). No when-not-to-use or alternative recommendations are provided.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by specifying the return fields (subscription IDs, plans, amounts, renewal dates) and pagination mechanism (limit and offset), providing behavioral context 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, no redundant words, and front-loads the core purpose. Every sentence adds necessary detail without extraneous content.

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

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

Given the tool's moderate complexity (5 documented parameters, output schema exists), the description covers purpose, filtering, return fields, and pagination. Authentication is handled via parameters. It is complete for an AI agent to use correctly.

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

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

Schema coverage is 100% with all parameters described. The description reinforces parameter usage: 'optional filtering by status' clarifies the 'status' parameter's role, and 'paginate with limit and offset' adds context 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 states the verb 'list' and resource 'subscriptions', with optional status filtering and specific return fields (IDs, plans, amounts, renewal dates). It distinguishes from sibling tools like 'chargebee_get_subscription' which retrieves a single subscription, and 'chargebee_list_customers' which is for a different entity.

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

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

The description provides clear context for when to use the tool: listing subscriptions with optional filtering and pagination. However, it does not explicitly exclude scenarios or mention alternatives like 'chargebee_get_subscription' for single subscriptions.

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, openWorld, idempotent, non-destructive), description reveals key behaviors: pulls latest 10-K data with proper fiscal year handling for companies, and FAERS/FDA/trial counts for drugs. Also mentions sorted results and citation URIs, providing rich behavioral context.

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 information-dense but front-loaded with trigger phrases. Every sentence adds value, but slight verbosity could be trimmed. Still well-structured and efficient.

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

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

Given complexity (two entity types, multiple data sources, sorting, citations) and no output schema, the description fully covers what the tool does, how it works, and what it returns. No gaps for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining that 'values' should be tickers/CIKs for companies and drug names for drugs, and specifies min/max constraints 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 defines the tool as performing side-by-side comparisons of 2-5 companies or drugs, using trigger phrases like 'compare X and Y' and 'which is bigger'. It explicitly distinguishes itself from sequential single-pack lookups and sibling tools like entity_profile.

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

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

Provides explicit guidance on when to use: when comparing, ranking, or head-to-head queries. States 'ALWAYS PREFER over sequential single-pack lookups' and clarifies the behavior for each entity type (company vs drug), including result sorting by primary metric.

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 carry readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, so the safety profile is covered. The description adds substantial non-redundant context: account/paid-tier prerequisites, 15-90s timing expectations, the never-invented guarantee (gaps[]), per-depth hop behavior, the always-fetchable citation_uri contract, and passage-level excerpting. Consistent with all 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?

Front-loaded with the most critical action (account requirement and fallback), and every sentence earns its place for a tool this behaviorally complex. However, it is a dense wall of text — multiple long interleaved topics (requirements, mode comparison, citation contract, excerpting, timing) — that could be broken into scannable chunks for an agent.

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 high complexity and the absence of an output schema, the description fully compensates: it documents the findings packet (verbatim evidence + confidence + source + fetched_at + citation), the gaps[]/contradictions[]/hop fields, timing, account prerequisites, and depth semantics. The one omission — no sample JSON of the return packet — is minor given how thoroughly the return contract is described in prose.

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% (question, depth), so baseline is 3, but the description adds real meaning on top: it explains the behavioral consequences of each depth level (quick=3 single hop; standard adds gap-recovery + contradictions[]; thorough=6 adds iterative lead-chasing, paid). This materially enriches what the enum labels alone convey.

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

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

States a precise verb+resource: 'Grounded multi-source research across Pipeworx's 1477 STRUCTURED data sources ... in ONE call'. Explicitly distinguishes from siblings twice — 'this is NOT open-web search' and the direct comparison to ask_pipeworx — so an agent can tell it apart without opening any schema.

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

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

Names the exact selection conditions: best for broad/multi-part questions over structured data ('compare X and Y's regulatory + financial exposure'), with named alternatives for excluded cases — 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. Also warns that uncatalogued topics return mostly empty gaps[]. Nothing is left to inference.

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, indicating a safe read operation. The description adds value by explaining that results come with full schemas and are ready to call directly, which goes beyond the annotations but doesn't disclose additional side effects or limitations.

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 and informative, covering domains, return format, and usage guidance. It could be slightly shorter but every sentence adds value, and the key points are front-loaded (verb+resource and when-to-use).

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

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

Given no output schema, the description explains what is returned: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' This is sufficient for the tool's purpose. No missing critical context like pagination or error handling, but acceptable for a discovery tool.

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

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

Schema coverage is 100% with all 6 parameters documented. The description does not add new parameter meaning beyond what the schema provides (aliases are explained). However, it mentions 'curated examples' which is extra context but not parameter-specific. Baseline 3 is appropriate.

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

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

The description clearly states the tool discovers tools by describing data or task, lists specific domains, and explains what it returns. It distinguishes from siblings like deep_research or search_within by positioning itself as a tool discovery mechanism with the directive 'Call this FIRST when you have many tools available'.

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

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

Explicitly says when to use: '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 and want to see the option set (not just one answer).' This provides clear context and usage boundaries.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds significant context: fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific fields, mentions patent soft-failure (USPTO API sunset May 2025), and notes that names are not supported. This enriches the behavioral understanding 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 but slightly lengthy; it front-loads example queries and provides detailed output structure. A more bulleted or list-style formatting could improve scanability, but every sentence adds value and the information density is high.

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

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

Given no output schema, the description fully explains return values (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and failure modes (patents soft-fail, names not supported). For a complex multi-source tool, this provides a complete picture for correct invocation.

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

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

Schema coverage is 100% with descriptions for both parameters. The description reinforces the schema by providing example values (e.g., 'AAPL' or '0000320193') and clarifying that names are not supported, adding meaningful guidance 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 provides a 'full cross-source profile of a US public company' with numerous example queries. It details the returned data (CIK, filings, fundamentals, patents, news, LEI) and explicitly distinguishes itself from 'chaining single-pack SEC/XBRL/news lookups', making its purpose distinct from sibling tools.

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

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

The description tells the agent to 'ALWAYS PREFER over chaining single-pack...lookups when the user asks for a holistic view', provides explicit when-not-to-use (if only have a name, use resolve_entity first), and notes limitations (patents soft-fail, only 'company' type supported). This gives clear guidance on when and how to invoke the tool.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true, so the description's job is light. The description adds 'delete' which aligns, but does not elaborate on whether deletion is permanent, what happens if the key doesn't exist, or other side effects. With annotations covering the core 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, zero fluff, front-loaded with action and usage conditions. Every word 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 tool's simplicity (one required parameter, no output schema, clear annotations), the description is fully complete. It covers purpose, usage context, and relationships to sibling tools.

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

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

Schema coverage is 100% with a single 'key' parameter described as 'Memory key to delete'. The description mentions 'by key' but adds no additional meaning beyond the schema. Baseline 3 is correct.

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

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

The description clearly states the action: 'Delete a previously stored memory by key.' It identifies the specific resource (memory) and the operation (delete), distinguishing it from sibling tools 'remember' and 'recall' which handle storage and retrieval.

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

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

Provides explicit guidance on when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data.' It also suggests pairing with 'remember' and 'recall', informing the agent of 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 safe, read-only behavior. The description adds valuable process details (fetches page, extracts title/description/key links, emits markdown format) without contradicting 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 compact and front-loaded with the core purpose, using three sentences to convey purpose, process, and use cases. Every sentence adds value 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 rich annotations and full schema coverage, the description adequately explains the output format (single text blob) and the tool's behavior. No output schema exists, but the description compensates by specifying the output use case.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal extra meaning beyond the schema's parameter descriptions (e.g., 'Full URL of the site to summarize' is similar to schema text). No further enrichment is needed.

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

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

The description uses a specific verb ('generate') and resource ('llms.txt'), clearly stating it works for any URL. It distinguishes itself from siblings by focusing on AI crawler indexing, a unique function not covered by other tools.

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

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

The description lists explicit use cases (client's site indexing, personal project, competitor audit), providing clear context for when to use. It does not explicitly state when not to use or name alternatives, but no sibling tool serves the same purpose, so this is minor.

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 readOnlyHint true, destructiveHint false, etc. Description adds value by explaining default behavior (returns only active subscriptions) and mentioning optional include_inactive parameter.

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: first states purpose and return fields, second gives usage guidance. 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 tool simplicity, good annotations, and no output schema, the description covers return values, usage, and parameter adequately.

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

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

Schema coverage is 100% and describes the parameter well. Description does not add extra meaning beyond what the schema provides.

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

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

Clearly states it lists the caller's active subscriptions and specifies return fields (id, type, params, created_at, etc.). Distinct from sibling tools like subscribe and unsubscribe.

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

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

Provides explicit when-to-use: 'review what you're monitoring before adding more or to find an id to cancel.' Lacks explicit exclusion criteria but gives clear context.

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

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

The description discloses several behavioral traits beyond the annotations: rate-limiting ('Rate-limited to 5 per identifier per day'), the claim_token workflow ('Filing without an account returns a claim_token; pass it back later ... to read whether it was fixed'), and quota impact ('Free; doesn't count against your tool-call quota'). These details meaningfully inform the agent of side effects and workflow, which annotations (all false) do not convey.

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

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

The description is front-loaded with purpose, then flows naturally into usage, exclusions, mechanics, and constraints. Every sentence earns its place—there is no fluff. Despite its length, it is tightly structured and each section is clearly delimited, making it easy for an agent to parse quickly.

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

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

The description fully equips an agent: it explains the tool's purpose, when to use it, what to avoid, how to track a submitted report via claim_token, response expectations, and rate limits. Even without an output schema, it covers the key return behavior (claim_token) and practical constraints, making it complete for a feedback tool.

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

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

Schema description coverage is 100%, so each parameter already has meaning. The description adds complementary guidance: for message, 'Be specific ... 1-2 sentences typical' and 'don't paste the end-user's prompt'; for context, it gives concrete examples (pack slug 'fred', tool 'fred_get_series'). This goes beyond the schema without redundancy, earning a 4 rather than the baseline 3.

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

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

The description opens with a clear verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly enumerates the feedback types (bug, feature, data_gap, praise) and differentiates itself from sibling tools by stating it only applies to this connection's tools, not other MCP servers. This is a specific, non-tautological purpose statement.

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

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

The description gives explicit when-to-use scenarios: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: 'if the tool came from a different MCP server ... file it with that server instead.' This is exemplary guidance for 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, destructiveHint. Description adds caching behavior (5min-1h) and data source (CF analytics-engine, no PII), providing value 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?

Well-structured, front-loaded with purpose, then use cases, then details. Every sentence adds value. 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?

No output schema, but description explains return values (top tools, top packs, call volume) and caching. Parameter fully covered. Adequate for a trending 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 enum description. Description adds context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' Enhances understanding.

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

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

Description clearly states the tool returns top tools, top packs, and call volume over a window. It distinguishes from siblings like ask_pipeworx and discover_tools by focusing on trending analytics.

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?

Lists three explicit use cases (discovering hot data sources, confirming canonical tools, aligning with agent needs). Lacks explicit 'when not to use', but context is clear.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint. Description adds detailed behavioral traits: semantic anchor (Jaccard similarity ≥0.30), partition filter for placeholder slugs, fill check against CLOB depth, and output structure with gap_pp, suggested_trade, etc. 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?

Well-structured and front-loaded with main action. However, it is somewhat verbose with sections like 'SEMANTIC ANCHOR:', 'PARTITION FILTER:', 'FILL CHECK:' which could be streamlined. Still clear and organized.

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

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

No output schema exists, but description fully explains the response structure: opportunities array with fields, partition_check object in event mode, and fill check conditions. Covers edge cases like skipped_low_similarity and placeholders_filtered. Very complete for a complex tool.

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

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

Schema coverage is 100% with descriptions for each param. The description adds substantial meaning: explains modes, accepted input formats (slugs, URLs, seed questions), processing logic, and examples. Significantly enhances 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 (no args, event, topic) and separates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly tells when to use each mode: 'Call with NO args for a trending_scan... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' Recommends event mode and gives conditions that should not be traded (realizable_edge_pp ≤ 0). References polymarket_fill_risk for custom sizing.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds detailed context: caching (1h at KV level), edge calculation methodology, model families, knobs, and response structure. 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 long but well-structured with sections and bullet points. Every sentence adds useful information for an agent to understand edge computation and parameters. Slightly verbose but not wasteful.

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

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

No output schema exists, but the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics) and all edge fields. It is complete for a complex tool with 9 parameters and multiple segments.

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

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

Schema description coverage is 100%, but the description adds meaning beyond field names, e.g., explaining why min_kelly doesn't filter partition arbs and how min_partition_leg_kelly applies. This helps the agent understand parameter interactions.

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 a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the tool's purpose and distinguishes from siblings like polymarket_arbitrage, polymarket_edge_tracker, etc.

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

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

The description says it is 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It explains tradeable-edge knobs and how to use them, but does not explicitly state when not to use this tool or compare it to alternatives.

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

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

Annotations already declare the tool as read-only and idempotent. The description extensively discloses behavior: response structure (tracked, expired, snapshot_dates), field meanings (trend, decay_pp_per_day, lifespan_days), and limits (60-day TTL, daily closes, no intraday). 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 relatively long but well-structured: purpose first, then output details, then limits. Each sentence provides useful information, but some redundancy with schema exists.

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

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

The description is very complete given no output schema: it explains the full response structure, field semantics, and data limitations. Covers edge cases like gaps in snapshots and median lifespan as competition clock.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description reiterates defaults and options but adds minimal new semantic value, mostly repeating what is in the schema.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily snapshots, answering a specific question about edge duration. It distinguishes from sibling polymarket_edges (current edges) by focusing on historical tracking.

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

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

The description implies when to use (for historical edge analysis) and provides context about fresh vs old edges. It mentions limits but does not explicitly exclude scenarios or name alternative tools for specific use cases.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering safety. The description adds substantial context: required parameter constraints, return values (top_of_book, vwap_fill_price, verdicts), and behavioral risks like thin_legs and forced_directional_risk. 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 well-structured: a summary sentence, then clear sections for single-market and basket modes with breakouts of return fields. All information is relevant for such a complex tool. While verbose, it earns its length given the richness of behavior.

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

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

No output schema is provided, so the description must explain return values fully. It does: listing all fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, capture_ratio, thin_legs, etc.) and explaining edge cases like forced directional risk. This makes the description complete for agent decision-making.

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

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

Schema description coverage is 100%, providing basic descriptions for all four parameters. The tool description adds significant value by explaining how size_usd interpretation differs between single-market and basket modes, clarifying the auto-detection logic for side in basket mode, and detailing default values and constraints 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 it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' with explicit single-market and basket modes. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on risk assessment before execution.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also warns about the dominant loss mode (partial basket fills converting arb into unhedged directional position), providing clear when-to-use and why.

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 (readOnlyHint, openWorldHint, idempotentHint) are consistent. Description adds extensive behavioral details: two calculation modes, response structure (leg prices, top spreads), safety fields explaining why some comparisons fail (non-equivalent bet shapes, temporal misalignment, skipped comparisons). 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?

Well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. While verbose, each sentence adds necessary information given 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 covers response structure and safety fields comprehensively. It explains temporal alignment, skipped comparison counters, and practical tradeability caveats, making it complete for an agent to understand tool behavior.

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

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

Schema coverage is 100%, but description adds significant value beyond schema: explains the 10 topic shortcuts, how explicit tickers override topics, and provides examples. This extra context justifies a score above baseline 3.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket, describes two modes (topic shortcuts and explicit tickers), and distinguishes it from sibling tools like polymarket_arbitrage by focusing on the spread across venues.

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 explains when to use each mode, warns that most pre-mapped topics return compatibility warnings, and describes safety fields (compatibility_warning, temporal_alignment) that indicate when spreads are not meaningful.

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, idempotentHint, destructiveHint; the description adds that the tool is scoped to an identifier (IP, key hash, account ID), providing useful behavioral context 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?

Three well-structured sentences, front-loaded with core action, no redundant 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?

For a simple tool with 1 optional parameter and good annotations, the description covers all needed aspects: purpose, usage mode, scope, and pairing with siblings. 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?

Schema coverage is 100% for the single optional 'key' parameter. The description adds meaning by explaining that omitting the key lists all saved keys, which is not in the schema.

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

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

The description clearly states the tool retrieves a value saved via remember, or lists all keys if key is omitted. It specifies verb and resource, and distinguishes from siblings like remember and forget.

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

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

The description advises using it to look up stored context without re-deriving, and mentions pairing with remember/forget. It could explicitly state when not to use, but the context is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds context on return fields, filtering, and the side-effect of mark_read on future calls. 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?

Concise and well-structured. Main action is front-loaded, followed by relevant details. Every sentence adds value 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?

No output schema, but description mentions return fields and alternative endpoint. Sufficiently complete for a data retrieval tool given the annotations and schema richness.

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 at 3. Description adds practical examples (e.g., 'sec_8k' for type) and explains mark_read effect, which goes beyond 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 it pulls fired events from the subscription feed and returns recent alerts with specific fields. It distinguishes itself from sibling tools like 'list_subscriptions' by focusing on alerts.

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

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

Provides guidance on filtering by type and since, and explains the mark_read behavior affecting subsequent calls. Mentions an alternative GET endpoint for scripts/dashboards, 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?

Annotations already indicate read-only, idempotent, non-destructive. Description adds substantial behavioral detail: fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO with soft-fail, return structure (changes grouped by source, total_changes, citation URIs), and PatentsView API sunset note. No contradiction with annotations.

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

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

Description is front-loaded with example queries and is well-structured. While it includes many specifics, every sentence adds value. Slightly lengthy but still efficient.

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

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

Despite no output schema, the description fully covers expected return data (structured changes by source, total_changes, citation URIs) and fallback behavior. All 3 parameters are explained, and the tool's purpose is clear.

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 `since` accepts ISO date or relative shorthand ('7d', '30d', '3m', '1y'), recommends '30d' or '1m' for monitoring, and clarifies `type` only supports 'company'.

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 provides a change feed for a company over a time window, with example queries like "What's new with X" and "updates on Acme". It explicitly distinguishes from sibling tool entity_profile for static profile.

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

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

Provides explicit guidance on when to use this tool versus entity_profile ('Use entity_profile instead when you want the static profile...'). Also implies usage for dynamic updates and gives example timeframes.

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 idempotentHint=true and destructiveHint=false are consistent with description. Description adds context about memory retention for anonymous vs authenticated users, enhancing transparency.

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

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

Description is informative and front-loaded with purpose. Every sentence adds value, though it could be slightly more concise. Overall well-structured.

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

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

For a simple key-value store with no output schema, the description is complete. It covers retention, scoping, and pairing with related tools, with no missing critical information.

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

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

Schema descriptions already cover both parameters (key, value) at 100% coverage. Description adds meaningful examples and context, such as key naming conventions and value types.

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

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

The description clearly states the tool saves data for reuse across conversations/sessions, with specific examples like tickers, addresses, and preferences. It distinguishes from sibling tools recall and forget.

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

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

Explicitly states when to use: when discovering something worth carrying forward. Also mentions pairing with recall and forget, and provides scoping and retention details.

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 behavioral context beyond the annotations (readOnly, idempotent, non-destructive). It discloses that calls cascade through multiple lookup endpoints internally, that LEI/FIGI enrichment degrades gracefully when upstream services are unavailable, and that unresolved identifiers are explicitly listed under `unresolved` rather than silently omitted. It also explains how ISINs map to legal entities via GLEIF, covering non-US issuers.

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

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

The description is long but densely packed with essential information. It is well-structured: starts with usage signals, then states purpose, then details each supported type, and ends with behavior notes. Every sentence contributes value, though the length may be slightly high for a tool with only two parameters; however, the complexity justifies it.

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

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

Given there is no output schema, the description does a thorough job of explaining both input and output behavior. It covers identifier types, source labelling, unresolved handling, graceful degradation, internal cascading, and even citation format for drugs. It also notes that using this tool replaces 2-3 manual lookups, making its role in the broader tool ecosystem clear.

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?

While schema coverage is 100%, the description enriches both parameters significantly. For `type` it explains the two enum values in detail (company vs drug) and what each returns. For `value` it provides concrete examples like 'AAPL', '0000320193', and 'ozempic' and clarifies the ISIN-to-LEI mapping for company lookups. This far exceeds the schema descriptions.

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

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

The description opens with concrete user queries and clearly states the tool's function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It distinguishes from siblings by noting it provides IDs needed by other tools and explicitly says 'Use FIRST whenever you have a name but need an ID.'

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

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

Explicit usage guidance is given: 'Use FIRST whenever you have a name but need an ID.' It also differentiates between company and drug types and explains what inputs are accepted (ticker, CIK, ISIN, name, brand, generic). This clarifies when to use it versus alternatives like entity_profile or compare_entities.

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. The description adds value beyond these by explaining the tool probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. 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 two sentences, front-loaded with the core purpose, and each sentence earns its place. 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?

Despite no output schema, the description outlines the return format (ranked list with score, confidence, signal density). It explains the process (probe, rank, surface) sufficiently for an agent to understand what to expect.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining that the first entity in the array is treated as the 'subject' for narrative, and provides usage hints for models and context, adding value beyond the schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and returns a ranked list. It distinguishes itself from the sibling tool ai_visibility_check (single entity) and compare_entities (generic comparison) by focusing on competitive AI presence audits.

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 a use case ('competitive AI-marketing audits') and an example question, implying when to use. It mentions it probes with ai_visibility_check, hinting at alternatives for single entities, but does not explicitly state when not to use or list all alternatives.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia first measurement can take 5-30 seconds, and sources_failed field is used. This goes beyond annotations.

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

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

The description is well-structured with clear sections and front-loaded purpose. However, it is slightly long with many details, some of which could be moved to a usage section. Still, it is efficient and contains 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 there is no output schema, the description compensates by listing the return fields (summary block, advisories, links, alternatives). It also explains error handling (sources_failed). For a tool with two parameters and no output schema, this is fully complete.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds context about default version behavior and the overall composite call, but doesn't provide substantial new meaning beyond the schema. However, it clarifies the purpose of the parameters in the context of the tool's action.

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: a composite check for evaluating npm packages across deps.dev and bundlephobia. It specifies the verb ('scan') and resource ('dependency'), and distinguishes from siblings by explicitly noting that other ecosystems belong elsewhere.

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: whenever an agent asks about safety, popularity, or size of an npm package. Also clarifies when not to use by stating 'NPM ecosystem only in v1' and directs to alternative tools for other ecosystems.

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?

Describes technical details beyond annotations: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K character cap with truncation flag, and output includes character offsets. Annotations already convey read-only and idempotent nature; description adds valuable implementation context.

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?

Efficiently front-loaded: first sentence states core purpose and key features. Uses bold for emphasis. Every sentence earns its place—no fluff, while covering algorithm, limits, and pairing guidance.

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?

Completes the tool's context: explains input limits (200K chars), algorithm (BGE embeddings, cosine), output format (passages with offsets and scores), and relationship to sibling tool. Despite no output schema, it adequately describes return values.

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, but description enriches parameters with examples (e.g., query examples like 'supply-chain risk'), constraints (200K char limit for text, limit range 1-20), and explains how text is processed (truncation flag). Adds significant value beyond 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?

Clearly states it performs semantic search inside a fetched record, with specific examples like SEC 10-K and articles. It distinguishes from sibling tools by specifying when to use (record too large for prompt) and mentions pairing with ask_pipeworx_grounded.

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

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

Provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt'. Mentions alternative workflow with ask_pipeworx_grounded, giving clear context for agent decision-making.

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 mutation (readOnlyHint=false) and idempotency (idempotentHint=true). Description adds that subscriptions are persistent and require authentication, details return value, and notes constraints (SMS cap, webhook auto-disable). 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 detailed but each sentence adds distinct information. Front-loaded with purpose. Could be slightly more structured (e.g., bullet points), but overall efficient for the complexity.

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

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

For a tool with 3 parameters (2 required), nested objects, and no output schema, the description fully covers return value (new subscription ID), type-specific parameters, delivery options, and prerequisites. No gaps remain.

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, but description adds significant value by providing concrete examples for each type (e.g., 'sec_8k: {ticker:, items?}') and explaining the nested params object with required fields. Delivery channel descriptions include usage notes and validation requirements.

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 verb 'Create' and resource 'subscription', clearly states 'proactive monitoring subscription to a live-data event stream'. Distinguishes from siblings like 'unsubscribe' and 'list_subscriptions' by focusing on creation and listing specific types and delivery channels.

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

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

Provides explicit context: requires Pipeworx OAuth account, supported types with examples, delivery channels with constraints (e.g., SMS requires verification, 10/day cap). Does not explicitly state when to avoid using this tool, but the detail is sufficient for correct 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 mark readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds context about returning example questions with tool+argument shapes drawn from the live catalog, and that calling with no arguments gives a full spread. 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?

Description is moderately long but well-structured: starts with alternative ways to invoke the tool, explains return value, then usage. Every sentence adds value, though slightly verbose for such a simple tool.

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

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

Given the simple one-parameter tool with no output schema but rich annotations, the description fully covers when to use it, what it returns, and how to customize. It is complete for an effective 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 one optional `topic` parameter. Description adds meaningful context by listing valid focus areas ('finance', 'pharma', etc.) and explaining that omission gives a cross-category spread, going beyond the schema description.

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

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

Description explicitly states the tool returns 'category-bucketed example questions' and identifies it as the onboarding entry point. It distinguishes from siblings by specifying that it is for when the agent does not know what Pipeworx can do, contrasting with meta-tools like ask_pipeworx and entity_profile.

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

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

Clearly instructs to 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions how to learn about calling meta-tools. Also explains the optional `topic` argument to focus on specific domains, giving explicit guidance on when 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 (readOnlyHint=false, destructiveHint=false) are complemented by the description's explicit statement that the row is 'deactivated (not deleted)' and that ownership is enforced. This adds valuable behavioral 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 extremely concise with two sentences, front-loading the main action in the first sentence. Every sentence adds value without any 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?

Given the tool's simplicity (one parameter, no output schema), the description covers all necessary aspects: action, enforcement, side effects, and consequences. It leaves no ambiguity for the agent.

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

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

The input schema has 100% coverage for the single parameter 'id', but the description adds relational context by noting that the id is 'returned by subscribe'. This helps the agent understand the parameter's origin, slightly exceeding 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 action 'Cancel a subscription by id' with a specific verb and resource. It effectively distinguishes itself from sibling tools like 'subscribe' (which creates) and 'list_subscriptions' (which lists).

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

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

The description implicitly provides usage context through ownership enforcement and the deactivation behavior. While it doesn't explicitly state when to use vs. alternatives, the sibling list and the explanation of historical events via 'recent_alerts' clarify the tool's role.

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

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

Annotations already cover safety (readOnly, idempotent, etc.), and the description adds critical behavioral context: verdict semantics, especially the crucial distinction between could_not_verify (check did not happen) and unsupported (no source found), plus the verification_error structure. This goes well beyond what annotations alone 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?

Although long, the description is dense and well-structured. It opens with trigger phrases, then explains routing, output, and critical caller warnings. Every sentence contributes essential information, and the 'IMPORTANT for callers' callout earns its place.

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

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

Given the tool's complexity (two pipelines, multiple verdicts, error semantics) and absence of an output schema, the description compensates thoroughly. It lists all verdict values, explains the citation output, and clarifies ambiguous result states. No obvious critical gap remains.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining tolerance_pct's role (overriding implied tolerance, using 1–2 for hallucination detection, default cap at 5) beyond the schema's raw description. This extra semantic context justifies 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 states a specific verb+resource: natural-language claim verification against authoritative sources, with trigger phrases. It clearly distinguishes itself from siblings by describing a unified pipeline that replaces 4–6 sequential calls, including a structured SEC EDGAR fast path for company-financial claims and a grounded pipeline for other claims.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the routing logic. However, it does not name alternative sibling tools (e.g., ask_pipeworx_grounded, deep_research) or state when not to use this tool, leaving some ambiguity for an agent choosing among research-related tools.

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