Outlook Contacts

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds critical behavioral context: the default free model (Workers AI Llama-3.3-70b), the requirement to bring your own API key for Anthropic, and the return structure (per-model {score, confidence, signals, raw_response} + combined view). This gives the agent a complete picture of behavior without contradiction.

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

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

The description is four sentences with no wasted words. It front-loads the purpose and immediately provides the key behavioral details. Every sentence adds necessary 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 tool's moderate complexity (4 params, no output schema), the description covers enough: it explains return format, use cases, and model options. Sibling tools are distinct, and annotations cover idempotency. No obvious gaps exist for effective agent 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 description coverage is 100% with each parameter well-documented. The main description adds extra value: it specifies the default model, explains the API key billing, and provides examples for the entity parameter (e.g., 'Pipeworx', 'OpenInvoice'). This goes 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 verb 'probe' and resource 'LLMs for what they know about a business/brand/product/topic', and specifies the output as a visibility score 0-100. It distinguishes itself from sibling tools like 'ask_pipeworx' (which queries one LLM) and 'scan_competitor_ai_presence' (which may scan multiple entities) by focusing on scoring visibility across models.

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 concrete use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' This gives clear context for when to use the tool. However, it does not explicitly state when NOT to use it or provide alternative tools for different scenarios.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, so the safety profile is covered. The description adds valuable behavioral context: it routes across 5,798 tools, fills arguments automatically, and returns stable citation URIs. There is no contradiction with the annotations.

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

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

The description is long but well organized: priority instruction, relevant domains, behavior, trigger phrases, examples, and a final 'START HERE' directive. Some lists are redundant, but almost every sentence contributes to routing or invocation 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?

For a tool with one required natural-language parameter and no output schema, the description is quite complete: it explains scope, behavior, result format, and gives concrete examples. It would be a 5 if it also named and excluded sibling alternatives explicitly.

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 is fully self-describing; all six properties are clearly documented aliases for the single 'question' parameter. The description's examples reinforce natural-language usage but do not need to add parameter-level detail. A baseline of 3 is appropriate given 100% schema description coverage.

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

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

The description clearly states the tool's function: routes a natural-language question to the appropriate data source and returns structured answers with pipeworx:// citation URIs. It is specific about the resource and behavior. However, it does not explicitly distinguish itself from sibling tools like ask_pipeworx_beta or 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?

The description gives strong guidance: 'PREFER OVER WEB SEARCH', enumerates many domains, lists trigger phrases, provides examples, and says 'START HERE for most questions'. It misses only explicit when-not-to-use guidance relative to nearby specialized siblings like deep_research or validate_claim.

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

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

The description adds meaningful behavioral context beyond the annotations: it is a live experimental router, candidates may be enabled at any time, currently no candidate is active, and it is a full working router rather than a fallback stub. This helps an agent understand that behavior may vary over time. The read-only, idempotent, and non-destructive annotations are not contradicted.

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 reasonably compact for the complexity it covers: identity, current experimental state, usage instruction, and fallback assurance. Some repetition exists between 'identical universal router' and 'currently matches ask_pipeworx exactly', but the emphasis is useful for a beta tool. It is front-loaded with the core identity.

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 is a beta wrapper around ask_pipeworx, the description covers the essential operational context: same tools, same arguments, same response shape, current equivalence to stable, and experimental purpose. No output schema exists, but the phrase 'same response shape' addresses that. It does not detail error behavior or rate limits, but that is acceptable for a router that inherits behavior from a known sibling.

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

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

Schema description coverage is 100%, so the parameters are already fully documented. The description only says 'same arguments' and does not add new semantic detail about how the question should be formatted or what kinds of questions work best. This meets the baseline but adds no extra value.

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

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

The description states it is a beta version of ask_pipeworx and a universal router with the same tools, arguments, and response shape. This clearly ties its purpose to ask_pipeworx and distinguishes it as the experimental variant. It stops short of explicitly stating 'answer a natural language question', but the title and sibling context make that clear.

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

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

It explicitly says to use it like ask_pipeworx when wanting the newest routing, and that results are compared against the stable router. It explains when the beta behavior is active and notes the current state matches ask_pipeworx exactly. It does not spell out scenarios where the stable version should be preferred, but the experimental framing implies it.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds substantial behavior beyond that: the extraction-only-from-tool-result guarantee, explicit refusal reasons, structured return shape, and one extra LLM call cost. No contradiction with annotations exists.

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

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

The description is dense but every sentence earns its place: purpose, behavior and return contract, when to use, and trade-off versus the sibling. The most important qualifier, hallucination-resistant, is front-loaded. It is long because the tool's behavior is genuinely nuanced, not because of filler.

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

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

No output schema exists, so the description correctly documents the full success and refusal return shapes. It also covers routing behavior, safety properties through annotations, cost trade-offs, and explicit usage conditions. Everything an agent needs to select and invoke this tool correctly is present.

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

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

Schema description coverage is 100%, so the schema already documents the single meaningful parameter and aliases. The description does not add much parameter-specific detail, but it reinforces that the tool fills arguments from the question. Baseline 3 is appropriate because the structured schema carries the load.

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

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

The description clearly states a specific verb+resource: a hallucination-resistant grounded answer mode for high-stakes reads. It explicitly differentiates itself from ask_pipeworx by noting it extracts answers only from tool results and includes a refusal pathway. An agent can distinguish it from siblings without opening any schemas.

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

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

Provides explicit when-to-use guidance: use whenever the answer will be quoted, cited, or acted on, and facts must not be invented. It also names the alternative ask_pipeworx and explicitly says to prefer it for casual lookups due to the extra LLM call cost. This is model guidance.

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

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

The description extensively covers behavioral traits beyond annotations: fan-out processes, response shapes, resolver contract with confidence levels, parent_event extraction, safety mechanisms for low-confidence and closed markets, wide-spread liquidity warnings, and cancellation rule parsing. No contradictions with annotations.

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

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

The description is long but well-structured with clear section headers and no redundancy. While it could be slightly more concise, every sentence adds necessary detail for a complex tool, justifying its length.

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

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

Given the tool's complexity, no output schema, and only 3 parameters, the description is exceptionally complete. It covers input, internal logic, output fields, edge cases, and security considerations, leaving no significant 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 the description adds value by explaining market input flexibility, depth options, and include_raw usage with size estimates. It also provides defaults and recommendations, augmenting the schema information.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, accepting slugs, URLs, or question text. It details the process but does not explicitly differentiate from sibling tools like 'polymarket_edges' or 'polymarket_arbitrage', leaving some ambiguity.

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

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

The description specifies use cases ('should I bet on X', 'what does the data say') and provides category-specific fan-out examples. However, it does not explicitly state when not to use the tool or suggest alternative tools for different scenarios.

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

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

Adds rich behavioral details beyond annotations: data sources (EDGAR/XBRL, FAERS), specific metrics, sorting behavior, citation URIs, and handles fiscal year offsets. 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?

Dense but well-structured: starts with trigger phrases, then explains behavior per type, sorting, and return value. 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 no output schema, description explains return values (paired data + citation URIs), covers both entity types, sorting, and edge cases (off-calendar fiscal years). Complete for a comparison tool.

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

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

Schema coverage is 100%, but description adds value by explaining what values mean (tickers/CIKs for company, names for drug) and giving examples, going 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 does side-by-side comparison of 2-5 companies or drugs, with specific trigger phrases and data types per entity. It distinguishes from siblings like entity_profile by emphasizing it replaces sequential lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and gives example queries, providing clear guidance on when to use this tool versus alternatives.

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

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

The description goes well beyond the readOnly/opemWorld/idempotent annotations by disclosing account requirements, latency expectations, gap[] behavior, contradictions[], citation_uri fetchability, the never-invented guarantee, and semantic excerpting of large records. Nothing in the description contradicts the annotations.

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

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

The description is long but densely packed with operational information: account requirement, alternative tool routing, core behavior, depth semantics, citation guarantees, and latency. It is front-loaded with the most decision-critical facts. Some sentences could be trimmed, but the length is largely earned by the amount of useful 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?

Even though there is no output schema, the description tells the agent what the findings packet contains, how gaps and contradictions are represented, what citation_uri means, how depth tiers affect behavior, and what runtime to expect. For a research tool of this complexity, this is an essentially complete operational picture.

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

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

The input schema already covers both parameters with 100% description coverage. The tool description adds meaningful nuance beyond the schema: the paid-plan gate for depth:'thorough', the second-hop gap-recovery behavior for standard versus thorough, and examples of acceptable natural-language questions. This is a real but modest increment over the schema.

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

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

The description names a specific capability: grounded multi-source research across 1,517 structured data sources in one call, and explicitly contrasts itself with open-web search. It also provides concrete examples ('compare X and Y's regulatory + financial exposure') and distinguishes itself from ask_pipeworx for single lookups, making the tool's purpose and scope unmistakable.

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

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

The description gives explicit routing guidance: use ask_pipeworx if not signed in, use ask_pipeworx for single lookups, and use deep_research for broad/multi-part questions over structured data. It also names depth:'thorough' as a paid tier, giving clear preconditions for 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 readOnly, idempotent, non-destructive. The description adds significant behavioral context: returns top-N relevant tools with full schemas and curated examples, ready to call directly without second lookup. This goes well beyond annotations.

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

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

Well-structured with purpose first, then domain list, then output description. Every sentence adds value, though slightly verbose with the long list of domains.

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 the return format (names, descriptions, schemas). It also covers the behavior of returning top-N results and being ready to call directly.

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 parameter descriptions are adequate. The description adds value by providing natural language query examples and clarifying that multiple aliases (task, q, etc.) are accepted.

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 'Find tools' and the resource 'by describing the data or task'. It lists many specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools, none of which are for tool discovery.

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

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

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set'. Provides clear context for when to use it, though it does not explicitly state when not to use it.

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

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

Beyond readOnly/idempotent annotations, the description discloses fan-out across multiple sources, the sources_used/sources_failed fields, empty sections meaning real 'no data,' private company behavior (resolved:false + notes), and type/value interchangeability. No contradiction with annotations.

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

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

The description is dense and front-loaded with the core purpose and the 'ALWAYS PREFER' guidance. It contains many necessary details about sources, returns, and edge cases; though a bit sprawling, every sentence adds useful 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 no output schema, the description provides a thorough account of return fields (cik, resolved_from/to, recent_filings, fundamentals, sources_used/failed), edge cases for private companies, and input variants, making the tool callable without requiring additional inference.

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 examples ('AAPL', '0000320193', 'Moderna'), clarifies that type accepts company/ticker interchangeably, and notes name resolution via SEC EDGAR. This is helpful extra context but the schema already defines the core semantics.

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

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

The description states a specific purpose: 'full cross-source profile of a US public company in ONE parallel call,' with concrete example user phrasings. It clearly targets holistic company research and distinguishes itself from chaining single-source lookups.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also explains acceptable input forms and how private companies are handled, giving an agent clear conditions for 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?

The description adds context beyond annotations by noting the use case for clearing sensitive data. Annotations already indicate destructiveHint=true and idempotentHint=true, and the description aligns with these without contradiction.

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

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

The description is two sentences, front-loaded with the core action, and contains no unnecessary words.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage guidelines, and context completely. Annotations further fill in behavioral details.

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

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

The description adds no additional meaning to the parameter beyond what the input schema provides. Schema coverage is 100%, so baseline is 3.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying the verb (delete), resource (memory), and method (by key). It also mentions pairing with 'remember' and 'recall', distinguishing it 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 explicitly states when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It does not explicitly mention when not to use, but provides sufficient context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, establishing a safe, non-destructive profile. The description adds basic steps (fetch, extract, emit) but no deeper behavioral context like rate limits or authentication needs.

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

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

The description is concise, front-loaded with the main purpose, and structured logically. Every sentence adds value, though it could be slightly more terse.

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, annotations, and schema coverage, the description provides adequate context about output format and use cases. Missing error handling or validation details, but acceptable for a read-only tool with openWorldHint.

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

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

Schema coverage is 100% with both parameters described. The description implicitly references the URL and max_links but adds no additional meaning or 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 the tool generates a production-ready llms.txt file for any URL, specifying verb, resource, and output. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on llms.txt generation.

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

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

Explicit use cases are provided: indexing a client's site, drafting for own project, or auditing competitors. However, it lacks explicit when-not-to-use or direct comparison to siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds the list of returned fields and the optional include_inactive parameter but does not disclose further behavioral traits beyond what annotations offer.

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, front-loaded sentences with no wasted words. Every sentence adds value: purpose and usage 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?

Despite no output schema, the description lists return fields. The single optional parameter is covered in schema. Sibling tools are present. Guidance on using the results (find id to cancel) makes it complete for a simple list tool.

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

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

Schema coverage is 100%, with one boolean parameter fully described in the schema. The description does not add parameter information beyond what the schema provides, so baseline score of 3 applies.

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

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

The description clearly states it lists the caller's active subscriptions, specifies the returned fields (id, type, params, etc.), and distinguishes 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?

It advises to use this tool to review monitored items before adding more or to find an id to cancel, providing clear context on when to use it versus alternatives. It lacks explicit when-not guidance but context is sufficient.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the safety profile is covered. The description adds useful context about the scope of returned data and the intended workflow, which is valuable given the lack of an output schema. No contradictory behavior is disclosed.

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 with no wasted words. It front-loads the core purpose, lists the key return fields, and ends with a clear usage directive.

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

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

For a simple one-parameter, read-only lookup tool with full schema coverage and robust annotations, the description is complete. It explains what is returned, when to call it, and how the ID is obtained, covering everything an agent needs to invoke it correctly.

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

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

Schema coverage is 100%, and the id parameter is already documented as coming from outlook_list_contacts. The description reinforces this by mentioning the ID and the prior list step, but it does not add substantive meaning beyond the schema.

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

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

The description states a specific verb ('Get'), a precise resource ('a single Outlook / Microsoft 365 contact by its ID'), and enumerates the meaningful fields returned. It is clearly distinguishable from siblings like outlook_list_contacts and outlook_search_people.

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 instructs the agent to use this tool after outlook_list_contacts and to read a full contact from the address book. It provides clear context and sequencing, though it does not explicitly mention when to prefer sibling tools like outlook_search_people.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the 'signed-in user' scope and a sense of the returned data, but does not mention potential auth failures or exact response shape; with annotations present, this is adequate but not exceptional.

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

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

Two sentences, no filler, with the action and resource front-loaded and the practical use case in the second sentence. Every word earns its place.

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

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

For a zero-parameter read-only profile getter, the description is complete: it names the resource, the returned identity fields, and the use case. Annotations handle the safety profile, and no output schema is needed for such a simple 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?

There are zero parameters, so the schema has nothing to document and the description naturally does not need to add parameter meaning. The description does mention the profile fields returned, which is semantically useful for the tool's output even though there is no output schema.

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

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

States a specific verb ('Get'), the exact resource ('the signed-in user's Microsoft 365 / Outlook profile'), and the returned fields (display name, email address, UPN). This clearly distinguishes it from sibling contact tools like outlook_get_contact and outlook_list_contacts.

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

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

The phrase 'Use to identify whose contacts and address book are connected' gives a concrete scenario for when to invoke this tool. It implies differentiation from the contact-focused sibling tools, though it does not explicitly name alternatives or exclusion criteria.

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

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

Annotations already declare readOnly, openWorld, idemponent, and non-destructive behavior, so the safety profile is covered. The description adds useful behavioral context by stating that results are 'compact contact records' with specific fields and that keyword search spans contact fields, which helps set expectations even without an output schema.

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

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

The description is four short sentences with no filler: purpose, return shape, search capability, and usage context each get one focused sentence. Information is front-loaded, and the mild repetition of 'Outlook / Microsoft 365' is negligible.

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

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

For a simple read-only list tool with two optional parameters, this description is complete: it states the resource, the return record fields, the search behavior, and a concrete usage case. The schema provides defaults, max, and examples, and annotations cover side-effect safety, so no critical information is missing 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?

The input schema describes both parameters fully and with 100% coverage, so the schema does the heavy lifting. The description only paraphrases the search paramter by mentioning keyword search across contact fields; it adds no additional paramter semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description gives a specific verb ('List') and resource ('Outlook / Microsoft 365 address book') and states what the returned records contain, so an agent can immediately understand the tool's core purpose. It does not explicitly differentiate the tool from sibling tools like outlook_get_contact or outlook_search_people, which prevents a 5.

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 final sentence ('Use to browse a user's saved Outlook / Microsoft 365 contacts') gives a clear intended context for when the tool is appropriate. However, it names no alternatives and provides no when-not-to-use guidance, so the routing decision is left partially implicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the description is not required to restate safety. It adds helpful behavioral context about relevance ranking, available match fields, and organizational scope. It does not cover return format, errors, or pagination beyond what the schema already provides via the 'top' 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?

The description is two sentences with no filler. The first sentence front-loads the operation, scope, ranking, and return fields; the second sentence gives a concrete usage scenario. Every sentence contributes useful 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?

For a low-complexity, read-only search tool with two parameters and no output schema, the description sufficiently explains what the tool does, what inputs are used for, and what kind of results are returned. The main gap is the absence of explicit output format detail, but the description already names the return fields and the schema covers result limits.

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

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

Schema description coverage is 100%, so the schema already documents both 'query' and 'top' adequately. The description restates that the query is free-text and matches names/emails, but adds little meaning beyond the schema. Baseline 3 is appropriate because the structured schema carries the semantic load.

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

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

The description names a specific verb ('Search'), defines the resource as people relevant to the signed-in Outlook/Microsoft 365 user, and explains the ranking basis. It also differentiates from sibling contact tools by noting that matches need not be in the saved address book.

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

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

The description explicitly states when to use the tool: to find a coworker or frequent contact by name. It implies a distinction from contact-list tools by mentioning 'even if they are not in the saved address book,' but it does not explicitly name alternatives or state when not to use it.

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

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

The description goes well beyond the sparse annotations (all hints false) by disclosing important behavioral details: filing returns a claim_token, rate limit of 5 per identifier per day, free and doesn't count against tool-call quota, and that the team reads digests daily. It also includes the guidance to describe issues in terms of Pipeworx tools, which is an unstated behavioral expectation.

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 carefully structured, starting with the core purpose, then use cases, exclusions, and operational details. Every sentence adds value, though some repetition exists (e.g., restating 'ONLY for tools served by this Pipeworx connection'). It remains highly readable and front-loaded, so a 4 is warranted.

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 (nested context object, optional params, no output schema), the description is fully self-contained. It covers all invocation modes, exclusions, the claim_token retrieval flow, rate limiting, quota impact, and what happens after filing. Nothing about usage seems omitted.

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 each parameter already well-described in the schema, so baseline is 3. The description adds extra semantic constraints: the message should not contain the end-user's prompt and the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"..."})'), which are not explicit in the schema. This added meaning 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 first sentence 'Tell the Pipeworx team something is broken, missing, or needs to exist' provides a specific verb+resource+scope. The description clearly enumerates use cases (bug, feature, data_gap, praise) and distinguishes this from tools on other MCP servers by explicitly stating it only applies to this Pipeworx connection.

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 directives (tool returns wrong data, wish for a new tool, positive note) and avoids misdirected feedback by stating that tools from other MCP servers should be reported elsewhere. It also provides the distinguishing criterion ('Pipeworx tool names are the ones this connection lists') and the claim_token workflow for follow-up, giving clear situational guidance.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true. The description adds valuable behavioral context: 'Self-aggregating signal — derived from CF analytics-engine, no PII' and 'Cached 5min-1h depending on window.' 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?

Description is well-structured with clear sections and bullet-like use cases. It is front-loaded but slightly verbose; each sentence adds value but could be more concise.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers what is returned (top tools, packs, volume, window), caching, and derivation. No gaps apparent.

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

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

Schema coverage is 100% and the description adds meaning: explains that shorter windows surface hot trends and longer windows show steady-state demand. This extends the enum values.

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 returns top tools, packs, and call volume over a window. It uses a specific verb ('Returns') and resource ('top tools, top packs, total call volume'), and distinguishes from sibling tools like discover_tools by focusing on trending usage from AI agents.

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 lists three use cases (discovering hot data sources, confirming canonical tools, aligning use cases). However, it does not provide exclusions or alternatives, which would improve guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds rich behavioral details: internal algorithms (Jaccard similarity, partition filter), fill check against CLOB depth, return format, and trade guidance. 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 with clear sections for modes, internal mechanisms, and return format. Every sentence adds value, though some redundancy exists (e.g., repeating partition check details). 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, so description must explain return values. It does: 'opportunities[]' with fields, and 'partition_check' object in event mode. Also covers fill check and trade decision logic. Complete for a complex analytical 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%, but the description adds significant meaning beyond schema: explains event slug examples, topic seed questions, and the internal logic behind each parameter. It also provides usage recommendations.

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 via monotonicity violations and partition-sum checks, and distinguishes three modes: no-arg trending scan, event mode for specific events, and topic mode for cross-event scanning. The verb 'find' and resource 'arbitrage opportunities on Polymarket' are specific.

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

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

Explicit guidance: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It explains when to use each mode and mentions cross-event mode catches patterns that single-event misses. Also references fill check and custom sizing via polymarket_fill_risk.

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 extensive behavioral traits beyond annotations, including caching at KV level for 1 hour, specific models and calculations (e.g., lognormal barrier, GDELT, partition_overround), response structure with diagnostics, and warnings like '24h-move warning'. This goes well beyond the read-only and idempotent hints provided by annotations.

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

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

The description is front-loaded with the purpose and well-structured, but it is lengthy with considerable technical detail (e.g., exact alpha values for sports). While all content is relevant, it could be more concise without losing 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?

Given the lack of an output schema, the description thoroughly explains the response structure, including top-level keys (by_segment, fed_candidates, _diagnostics) and field details within opportunities (edge_pp_net, kelly_fraction, etc.). This fully compensates for the missing output schema.

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

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

All 9 parameters have schema descriptions, providing baseline insight. The description adds integrated context, such as explaining how tradeable-edge knobs (min_liquidity, max_spread_pp) interact and detailing the purpose of min_partition_leg_kelly. This adds value beyond the standalone 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 scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, using the specific verb 'scan'. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by detailing three unique segments (model-driven, structural arbitrage, concentrated longshot) and the 'what should I bet on today' use case.

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

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

The description implies usage for discovering betting opportunities and provides guidance on knobs, but does not explicitly state when not to use this tool or compare it to alternatives like polymarket_arbitrage or polymarket_edge_tracker. Given the presence of sibling tools, explicit differentiation would improve the score.

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?

Disclosures about response structure (tracked, expired, snapshot_dates), field meanings (trend, decay_pp_per_day, lifespan_days), and limits (60-day TTL, snapshot gaps) go well beyond the readOnly and idempotent annotations.

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

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

Well-structured with purpose first, then response details and limits. Slightly lengthy but every sentence adds value; no redundancy.

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

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

Despite lacking an output schema, the description thoroughly explains all response fields and their interpretations, including edge cases like gaps in snapshots. Complete for the tool's purpose.

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?

Adds clarity to both parameters: explains default, max, and clamp for 'days'; explains 'window' as snapshot family with defaults. This supplements the schema which already has 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?

Clearly states it provides edge persistence and decay telemetry from daily snapshots. Distinguishes from sibling 'polymarket_edges' by focusing on historical trends rather than current snapshots.

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?

Explains the use case via the question 'how long has this edge existed and is it shrinking?' and contrasts fresh vs old edges. Does not explicitly list alternatives or negative cases, 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?

Discloses detailed behavior: walks the ladder, returns top_of_book, vwap_fill_price, slippage_pp, verdict, etc. Warns about forced directional risk. Annotations already indicate readOnly, but description adds significant 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?

Well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). However, somewhat lengthy; some details could be trimmed or moved to parameter descriptions. Still 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?

Comprehensive coverage: both modes explained, all return fields mentioned, practical usage advice, and risk warnings. No output schema, but 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?

Schema coverage is 100%, but description adds valuable context beyond schema definitions: explains default for side in basket mode, interpretation of size_usd for buys vs sells, and the difference between single-market and basket parameters.

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

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

States specific purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' Clearly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly mentioning when to use this check before acting on those signals.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains dangers of thin books and partial fills.

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

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

The description goes far beyond the readOnly/idempotent annotations: it discloses that matching is by keyword overlap with 'pairing_unverified' set in EITHER mode, that the tool does not model Kalshi's fee schedule so every spread_pp is gross, and that legs with unknown metric_type/match_subtype are never paired. It pins down null semantics for temporal_alignment ('null means it could not be computed, not that the two sides align') and warns that compatibility warnings can be non-empty even when matched_pairs>0. This is precisely the behavioral context an agent needs to avoid over-trusting the spread numbers.

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

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

The description is a single dense wall of text; every sentence carries real content, but scannability suffers and there is redundancy — 'EITHER mode' is said twice and temporal_mismatch/temporal_alignment_unknown appear in both the compatibility_codes list and the per-entry flags list. The most operationally critical caveats (fees are gross; pre-mapped ≠ tradeable) arrive last rather than being front-loaded. Dense and non-tautological, but structurally it should be bulleted or reordered.

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

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

With no output schema, the description carries the full burden of explaining the return shape and does so thoroughly: leg-by-leg prices, top_spreads_pp with per-entry flags, compatibility_warning/compatibility_codes dual form, temporal_alignment, fees_note, and the skipped_cross_type/subtype counters. Given the tool's complexity — three optional params, two modes, and a rich caveat surface — nothing an agent needs to invoke it and interpret results 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%, so the baseline is 3; the schema already describes each parameter and the override behavior ('Overrides the topic-mapped... side'). The description adds the two-mode framework that binds the parameters together — topic mode vs explicit mode — and states that both modes run the identical matcher, which is meaning beyond the individual field descriptions. It stops short of giving fuller syntax details (e.g., ticker formats beyond one example), so a modest 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?

Opens with a precise statement of function — 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' — naming a specific verb, the two resources, and the scope ('same resolving question'). The cross-venue framing distinguishes it from Polymarket-only siblings like polymarket_edges and polymarket_arbitrage without needing to name them.

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 TWO MODES breakdown tells an agent exactly when to pass `topic` ('10 pre-mapped macro shortcuts') versus explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings, and clarifies that both run the identical token-overlap matcher. The closing warning — 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable' — sets accurate expectations for shortcut use. It never names sibling alternatives or exclusion conditions, which keeps it a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scoping detail ('Scoped to your identifier'), which is valuable beyond 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?

Four sentences with no fluff. Core action stated first, usage context second, scoping and sibling references follow. Every sentence earns its place.

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

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

For a tool with one optional param, no output schema, and annotations covering safety, the description fully covers purpose, usage, scoping, and sibling relationships. Nothing obvious 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 description 'Memory key to retrieve (omit to list all keys)'. Description further clarifies the parameter behavior ('omit the key argument to list all keys'), reinforcing schema info.

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 action ('Retrieve a value previously saved... or list all saved keys'), identifies the resource (memory key), and distinguishes from sibling tools (remember, forget). The verb 'recall' and resource 'value' are specific.

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 to look up context the agent stored earlier... without re-deriving it from scratch') and mentions pairing with remember and forget. Could state when not to use but context suffices.

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 claims mark_read:true flags events as read, implying a side-effect, which contradicts the annotation readOnlyHint=true. This is a serious inconsistency that misleads about the tool's safety profile.

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

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

The description is concise with four sentences, front-loading the main purpose. It could be more structured but contains 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?

Given no output schema, the description provides return field details, filtering, mark_read behavior, and alternative access. It lacks explanation of pagination and ordering, but is fairly complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds context only for type, since, and mark_read. It does not explain limit or unread_only beyond the schema, so the added value is partial.

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 pulls fired events from the subscription feed, specifies the return fields (source, citation_uri, raw payload), and distinguishes it from sibling tools by focusing on recent alerts 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?

The description mentions that polls work fine and provides an alternative access method (GET endpoint), giving clear usage context. However, it does not explicitly compare with sibling tools or 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already indicate safety. The description adds rich behavioral details: fan-out to multiple APIs, fallback from GDELT to GNews, soft-fail for USPTO due to sunset, and the return structure (changes[], total_changes, citation URIs). 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 a single dense paragraph. It is front-loaded with example queries but could be more scannable with breaking into sentences or bullet points. However, every sentence adds value—no fluff. It earns a 4 for being effective but slightly unstructured.

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 3 parameters, full schema coverage, and rich annotations, the description covers the return format (changes[], total_changes, URIs), source details, fallback mechanisms, and when to use the sibling tool. No output schema exists, so the description compensates well by outlining the return structure. The agent has all necessary context to invoke correctly.

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

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

Schema coverage is 100%, so descriptions for all three parameters are present. The description expands on the 'since' parameter with examples ('2026-04-01', '7d', '30d', '3m', '1y') and a recommended default ('30d' or '1m'). For 'value', it clarifies ticker or CIK format. The 'type' parameter is noted as only 'company' supported. While helpful, the description doesn't detail how each parameter affects the fan-out logic, leaving room for improvement.

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 user-facing example queries ('What's new with X') and clearly states it's a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It identifies the verb as 'recent changes' and distinguishes from the sibling 'entity_profile' by contrasting dynamic vs. static profile. The purpose 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?

The description explicitly tells when to use the tool ('change feed...') and when to use the alternative ('Use entity_profile instead when you want the static profile...'). It also outlines the data sources (SEC EDGAR, GDELT→GNews, USPTO) and fallback behavior, providing situational guidance.

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

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

Annotations already provide idempotentHint=true, but description adds valuable behavioral details: scoped storage, persistence differences between authenticated and anonymous users (24 hours), and pairing with recall/forget. 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?

Four clear sentences with no filler information. Purpose stated first, followed by usage guidance, then storage details. 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 only 2 simple parameters, no output schema, and good annotations, the description fully covers usage, storage semantics, 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 already covers both parameters with descriptions. The description adds example keys (subject_property, target_ticker) and clarifies the value as any text, slightly exceeding schema detail.

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

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

Clearly states the tool saves data for reuse across sessions, with specific examples of what to store (ticker, address, preference). Distinguishes from siblings (recall, forget) by implication.

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

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

Explicitly mentions when to use ('when you discover something worth carrying forward') and pairs with recall/forget. Does not explicitly state 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which already signal safe operations. The description goes well beyond that, disclosing internal cascading through multiple endpoints, graceful degradation of LEI/FIGI when sources are unavailable, the behavior when multiple matches occur (returns figi_candidates), and that unresolved identifiers are explicitly listed under `unresolved`. It also notes source labeling for each identifier. This is rich behavioral context that the annotations do not provide.

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

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

The description is long, but it is densely packed with instructional content, covering two entity types, multiple data sources, edge cases, and failure modes. It is front-loaded with the core purpose and the 'Use FIRST' directive. While it could be pruned slightly, every sentence earns its place; the length is acceptable for the tool's complexity. It is not bloated or redundant.

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

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

Given the tool has two distinct modes, multiple external sources (EDGAR, GLEIF, OpenFIGI, RxNorm), and a no-output-schema environment, the description is exceptionally complete. It covers what each type returns, how ambiguous names are handled, what happens when sources fail, and even mentions the citation format (pipeworx://rxnorm/concept/...). There are no significant gaps an agent would need to guess about.

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

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

With 100% schema description coverage, the schema already documents both parameters. The description adds substantial value: it explains the exact input format (e.g., for bonds use issuer name exactly as printed, never the full noun phrase), gives examples for both types (AAPL, 0000320193, 'ozempic'), and clarifies that for drugs it returns RxCUI plus brand. It even warns about trailing words that break FIGI lookup. This goes far beyond the schema's basic type description.

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

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

The description states the core purpose very specifically: "resolve a user-spoken NAME to the canonical/official identifiers other tools require as input." It enumerates query patterns (ticker, CIK, LEI, RxCUI) and supported entity types (company, drug) with concrete examples. It clearly distinguishes itself from siblings by focusing on name-to-identifier resolution, even noting that 'using resolve_entity replaces 2-3 manual lookups'.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains when NOT to use it—when a name maps to multiple instruments, it returns candidates rather than asserting one—and provides detailed instructions for each type (e.g., 'Pass the ENTITY NAME ONLY'). It even warns against including trailing security-class words. This is far more than vague context; it is actionable selection advice.

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

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

Annotations already indicate readOnly, idempotent, openWorld, and non-destructive behavior. The description adds details about the internal process (calls ai_visibility_check for each entity), ranking, and output structure (score, confidence, signal density). No contradiction.

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

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

The description is three concise sentences: purpose, process, and use case/output. Front-loaded with the primary action, no filler.

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

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

Given no output schema, the description adequately explains return format (ranked list with scores). It also addresses the special handling of the first entity. Slightly more detail on output structure would improve completeness, but it is sufficient for effective use.

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

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

Schema coverage is 100%, but the description adds beyond it: explains that the first entity is treated as the subject for narrative, clarifies that models defaults to workers-ai, and provides concrete examples for the context parameter. This adds significant semantic value.

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

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

The description clearly states the tool compares AI visibility across multiple entities, uses ai_visibility_check internally, and returns a ranked list. It distinguishes itself from the sibling 'ai_visibility_check' and 'compare_entities' by specifying side-by-side comparison.

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

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

The description explicitly mentions the tool is useful for competitive AI-marketing audits with an illustrative example. However, it does not explicitly state when to use alternatives like ai_visibility_check for single entities, though this can be inferred from the mention of probing each entity with that 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 readOnly, openWorld, idempotent, and non-destructive. The description adds significant behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. 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 yet comprehensive. It front-loads the composite nature and use case. Every sentence conveys useful information without redundancy. The structure flows logically from purpose to details to error handling.

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 lists the return fields (summary block, per-advisory detail, links, alternative versions). It covers edge cases like partial failures. Given the tool's complexity and rich annotations, the description is fully adequate.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by specifying scoped packages are accepted for 'package' and clarifying the default behavior for 'version'. It provides examples that enhance understanding beyond the schema.

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

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

The description clearly states it is a composite check for npm packages, combining deps.dev and bundlephobia. It specifies the exact purpose: evaluating safety, popularity, size. This distinguishes it from sibling tools which are broader research or platform-specific 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?

Explicitly states when to use: when an agent asks about safety, popularity, size, or cost of adding a package. Also provides exclusions: NPM only in v1, and directs to deps.dev:version for other ecosystems. This offers clear guidance on 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?

Despite comprehensive annotations (readOnlyHint, openWorldHint, etc.), the description adds rich behavioral context: embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), input limit (200K chars with truncation flagging), and output details (passages with offsets and scores). No contradictions with annotations.

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

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

The description is compact yet comprehensive, with purpose front-loaded in the first sentence. Every sentence adds unique value—no redundancy or filler. Ideal length 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?

The description covers all aspects: input (text, query, limit), output (passages with offsets and scores), algorithmic details, and usage pairing. Even without an output schema, the description sufficiently explains return values, making the tool fully understandable.

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% description coverage for all three parameters, providing basic meaning. Description adds valuable context beyond schema, such as example queries and implicit behavior (e.g., 'limit' defaults to 5). This extra context elevates the 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 'Semantic search INSIDE a fetched record' with specific verb and resource. It distinguishes from sibling tools like 'ask_pipeworx_grounded' by mentioning pairing, making uniqueness clear.

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

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

Explicitly provides when to use: 'when the record is too big to cram into the prompt' and suggests pairing with 'ask_pipeworx_grounded' as an alternative context, offering clear usage guidance.

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

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

Adds behavioral details beyond annotations: OAuth requirement, subscription types, delivery options including webhook signing and SMS rate limits. No contradiction with annotations (idempotent, non-destructive, open-world).

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 thorough but efficient; packs necessary details without redundancy. Could be slightly tighter but remains well-organized with key info 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?

Covers all essential aspects: purpose, prerequisites, types, parameters, delivery channels, and return value. No output schema exists, but description adequately specifies the subscription id.

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?

Despite 100% schema coverage, description provides rich examples for each type's params and delivery options, adding significant meaning and usage context beyond the schema.

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

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

Description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses a specific verb and resource, and distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

Includes prerequisite ('Requires a Pipeworx OAuth account') and discusses alternative delivery channels. Could explicitly state when not to use, but provides adequate context for 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 already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details such as the return format (category-bucketed examples with exact tool+argument shape) and the ability to call with no arguments for a full spread. There is no contradiction with annotations.

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

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

The description is three sentences long, front-loaded with common queries, and packs substantial information without unnecessary fluff. Slightly verbose due to listing all categories, but generally 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 the tool has only one optional parameter, no output schema, and rich annotations, the description fully explains what the tool does, how to use it, and why. It covers the return value, usage patterns, and relationship to sibling tools, making it complete for the task.

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% (one optional parameter with description). The description adds that calling with no arguments gives a 'full spread' and that passing a topic focuses results. This adds some value but does not significantly extend the schema's clarity; 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 that the tool returns category-bucketed example questions for onboarding, using specific verbs like 'returns' and 'call'. It distinguishes itself from sibling tools by positioning as the entry point for new agents, saying 'Use this FIRST when you do not yet know what Pipeworx can do for you.'

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

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

The description provides explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It names related tools (ask_pipeworx, entity_profile, etc.) but does not explicitly specify when not to use it, which is acceptable given the onboarding 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?

Discloses key behavioral traits beyond annotations: ownership enforcement, deactivation vs deletion, and impact on historical events. No contradictions with annotations; the description adds valuable 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?

Two concise sentences front-load the key action, followed by important behavioral details. No filler or repetition.

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

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

Given the tool's simplicity (single required parameter, no output schema), the description fully covers purpose, constraints, and side effects. 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?

Only one parameter 'id' with schema description 'Subscription id (uuid) returned by subscribe.' The description adds no additional semantics beyond what the schema already provides. With 100% schema coverage, 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 action ('Cancel a subscription') and the resource ('by id'). It effectively distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying the operation and scope.

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

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

Provides explicit guidance on ownership enforcement ('you can only cancel your own subscriptions') and the nature of the cancellation ('deactivated, not deleted'), including the rationale for historical availability via recent_alerts. This helps the agent choose this tool appropriately.

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 critical semantic context: 'could_not_verify' means the check did not happen and must not be treated as evidence, while 'unsupported' means no source covers it. It also explains how the grounded pipeline vs structured fast path behave, which is not available in annotations.

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

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

The description is dense but every sentence serves a purpose: trigger phrases, usage context, routing logic, return values, and caller warnings. It is long but appropriate for the tool's complexity, though it could benefit from bullet-point formatting for easier scanning.

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

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

Without an output schema, the description fully explains the return envelope: verdict enum, actual value with pipeworx:// citation, and reasoning. It thoroughly disambiguates failure modes (could_not_verify vs unsupported) and explains how the tool replaces a multi-step workflow. This is complete for the tool's complexity.

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

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

Schema coverage is 100% and both parameters (claim, tolerance_pct) already have detailed descriptions. The tool description adds nothing beyond the schema, though the mention of 'exact percent-delta math' subtly reinforces tolerance_pct's role. Meets baseline but does not exceed it.

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

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

The description uses specific verbs ('verify', 'fact check', 'confirm or refute') and identifies the resource (natural-language claims) and the output (a verdict with evidence). It clearly distinguishes itself from sibling tools by positioning as a single-call verifier that replaces 4–6 sequential pipeline steps.

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 'Use whenever the agent needs to check whether something a user said is factually correct' and provides routing rules for company-financial claims vs any other factual claim. It does not name alternative sibling tools or give specific when-not-to-use cases, but the guidance is clear and actionable.

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