Send That Email

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds value by explaining the probe nature, return structure (per-model scores, confidence, signals, raw_response), and cost details (free default, BYO key for Anthropic). 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 a single, well-structured paragraph that front-loads the purpose and key details. It is concise with no fluff, though a bulleted list could improve scannability.

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 explicitly states the return structure (per-model fields + combined view). It covers all parameters and provides sufficient context for a probe tool with good annotations. Minor missing details like rate limits or error handling, but overall adequate.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds some context beyond schema (e.g., default model, apiKey passthrough to Anthropic), but the schema already thoroughly describes each parameter. The added value is marginal.

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

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

The description clearly states the tool probes LLMs for knowledge about a business and scores visibility 0-100 per model. It uses specific verb 'probe' and resource 'LLMs' with a clear output. It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on scoring visibility.

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 context on when to use (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains model choice with cost implications (free default vs. BYO key for Anthropic). However, it does not state when not to use the tool or mention alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, lowering the bar for the description. The description adds useful context beyond annotations: it routes to one of 5,724 tools, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. It does not discuss rate limits or failure modes, but the annotation coverage makes this a minor gap.

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 most important routing instruction ('PREFER OVER WEB SEARCH') and organized into clear guidance: when to use, examples, and when to escalate. It is longer than the minimum, but every sentence adds either routing guidance, examples, or sibling differentiation; only slight redundancy around 'current' and 'factual questions' prevents a 5.

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-parameter tool with rich annotations and no output schema, the description covers what an agent needs to choose and invoke it correctly: trigger phrases, example queries, behavior, output citation format, and escalation paths. Nothing essential is missing for successful selection and 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?

The schema covers 100% of parameters and documents that question accepts aliases (query, q, prompt, text, input), so the description does not need to add much. The examples do reinforce the question format, but the description adds no deeper semantic explanation 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?

States a specific verb-resource pair ('Ask Pipeworx') and a precise scope: factual questions about real-world entities and numbers across a broad set of categories. It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives, so the agent can tell them apart without opening their schemas.

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

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

Explicitly says 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and gives exact step-up conditions for ask_pipeworx_grounded and deep_research. It also lists concrete example queries and covers the breaking-news edge case, leaving no ambiguity about when to choose this tool.

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

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

Annotations already establish readOnly, openWorld, idempotent, and non-destructive behavior, lowering the bar. The description goes well beyond by revealing this is an experimental live candidate, that no candidate is currently active as of 2026-07-26, and that it 'Falls back to nothing — this IS a full working router'. This discloses the operational and safety-relevant behavior without contradicting 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?

Four sentences, all information-bearing: beta status, equivalence with stable, current state, and no-fallback caveat. The essential context is front-loaded and no sentence is filler.

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

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

Given the tool is equivalent to a stable sibling, the description accounts for its experimental nature, argument equivalence, response shape, and usage condition. The absence of an output schema is partially mitigated by noting the response shape matches ask_pipeworx, though it does not describe that shape directly. Overall, it is complete enough for safe and correct invocation.

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

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

Schema coverage is 100%, with every alias explicitly described and 'question' documented as accepting natural language with aliases. The description only states 'same arguments' and does not add new parameter meaning beyond the schema. Therefore the baseline score of 3 is appropriate.

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

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

The description immediately identifies the tool as 'Beta version of ask_pipeworx' and explains it is the same universal router with the same 5,724 tools, arguments, and response shape. This makes the purpose concrete and differentiates it from the stable sibling. It clearly states what it does: an experimental edge of the same routing tool.

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

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

It explicitly says to 'Use it exactly like ask_pipeworx when you want the newest routing', which gives a clear decision criterion. It also contrasts with the stable router by noting results are compared against it. However, it does not explicitly state when to prefer ask_pipeworx or ask_pipeworx_grounded instead, so exclusions are implicit rather than fully spelled out.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds meaningful context beyond that: it details the success response shape, the explicit refusal format, the five refusal reasons, and the routing-to-fetch-to-extract pipeline. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: it front-loads the tool's core value and routing, then explains return contracts, refusal conditions, use cases, and cost trade-off. It is appropriately sized for a high-stakes tool with no output schema.

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

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

There is no output schema, so the description fully carries the burden of explaining return values and failure modes. It covers success shape, refusal shape, every refusal reason, and the primary use case. For a tool of this complexity, an agent has what it needs to call, interpret, and decide whether to use it.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters and their aliases. The description reaffirms that the question is in natural language but does not add meaning beyond what the schema provides, matching the baseline of 3.

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

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

The description states a specific verb and resource: it is a 'hallucination-resistant answer mode for high-stakes reads' that routes to the right tool, fetches data, and extracts answers only from tool results. It explicitly distinguishes itself from ask_pipeworx by name and by behavior, so an agent can identify it without 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 gives explicit when-to-use guidance: use whenever an answer will be quoted, cited, or acted on and the agent must not invent facts, with concrete examples. It also names the alternative ask_pipeworx and says to prefer it for casual lookups, along with the cost trade-off of one extra LLM call.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds extensive detail on resolution, classification, fan-out, safety short-circuits, and edge cases, fully disclosing the tool's behavior.

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

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

The description is front-loaded with core purpose but becomes verbose with extensive examples and technical details. While valuable, some information could be streamlined without losing utility.

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

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

Despite no output schema, the description thoroughly covers all response fields (market, analysis, evidence, resolver, parent event, news) and safety flags, 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 coverage is 100%. The description enriches each parameter: market can be slug, URL, or question; depth controls evidence sources; include_raw toggles payload size. This adds significant meaning beyond the schema.

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

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

The description clearly states 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' This provides a specific verb and resource, and the detailed behavior distinguishes it from siblings like polymarket_edges.

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

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

The description gives explicit usage contexts: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' However, it does not mention when not to use or name alternative tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false. The description adds rich behavioral context: data source (SEC EDGAR/XBRL, FAERS), specific metrics pulled (revenue, net income, cash, debt for companies; adverse-event counts for drugs), handling of off-calendar fiscal years, and result sorting by primary metric. No contradiction with annotations.

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

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

The description is front-loaded with examples and reasonably concise. It could be slightly trimmed, but every sentence adds value. Structure is clear and informative.

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

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

Given no output schema, the description explains return format (paired data + citation URIs) and covers edge cases (off-calendar fiscal years). It fully equips the agent to use the tool correctly for both entity types.

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 beyond schema by explaining what each 'type' enum value retrieves and providing concrete examples for 'values' (tickers/CIKs for company, drug names).

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, with explicit examples like 'compare X and Y' and 'X vs Y'. It distinguishes from sibling tools (e.g., entity_profile) by specifying this is for comparison, not single entity lookup.

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 instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing strong usage guidance. It does not explicitly state when not to use it (e.g., more than 5 entities), but the context is clear.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses account and pricing requirements, the gaps[] vs 'never invented' behavior, hop fields and resolvable citation_uri, semantic excerpting instead of head-truncation, contradictions[] output, and latency ranges. This substantially exceeds what annotations alone convey, and nothing contradicts them.

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 most critical gating information (account required) is front-loaded, followed by capability, alternatives, and depth semantics. It is dense and thorough rather than bloated, though there is minor redundancy around gaps[] and citation_uri appearing twice. Every sentence carries operational weight.

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

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

For a tool with no output schema, the description fully compensates: it explains findings packet fields, gaps[], contradictions[], timing, authentication, pricing tiers, depth behavior, and alternative routing. An agent has everything needed to select and invoke this tool correctly.

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

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

Even though schema coverage is 100%, the description enriches both parameters meaningfully: question is clarified as natural-language and broad/multi-part, and depth is expanded from a facet count into paid-plan requirements, gap-recovery hops, lead-chasing, and contradiction scans. This is genuine added value beyond the schema's enum 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 states a highly specific verb and resource: 'Grounded multi-source research across Pipeworx's 1497 STRUCTURED data sources' that decomposes questions and returns a findings packet. It explicitly distinguishes itself from open-web search and from sibling ask_pipeworx, leaving no ambiguity about what it does.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and for breaking news 'prefer ask_pipeworx'. It also gives an account-gated fallback ('If you are not signed in, use ask_pipeworx instead').

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?

While annotations already declare readOnlyHint=true, idempotentHint=true, etc., the description adds valuable behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and states results are 'ready to call directly, no second schema lookup needed.' This provides clear expectations of the output format and usability.

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

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

Description is moderately long but front-loaded with the core purpose. Every sentence adds value: examples, return format, usage guidance. Minor redundancy in listing aliases could be trimmed, but overall well-structured.

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

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

Given the tool's complexity (6 params, 1 required) and the absence of an output schema, the description fully covers what the tool does, when to use it, and what it returns. It explains that each result includes schemas and examples, making the tool self-contained. No gaps for the intended use case.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add additional meaning beyond what the schema already provides (e.g., natural language description, aliases). The examples in the input schema help, but the description itself offers no extra parameter guidance.

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 verb+resource: 'Find tools by describing the data or task.' It lists numerous example domains and explicitly distinguishes from other tools by stating 'Call this FIRST when you have many tools available and want to see the option set.' This differentiates it from sibling tools like search_within or deep_research.

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

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

Description explains when to use this tool (browse, search, look up) and contrasts with 'not just one answer,' implying it is for discovering options rather than getting a single answer. However, it does not explicitly name alternatives or state when not to use it.

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

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

Discloses important behavioral traits: the tool makes one parallel call, fans across multiple sources, and notes that the patents API sunset in May 2025 (soft-fails until reactivated). This adds significant value beyond the readOnlyHint and idempotentHint annotations.

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

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

The description is well-structured with an opening block of example queries, then a clear list of returned data sources. While it is relatively long, every sentence contributes value; minor redundancy could be trimmed but overall 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 complexity (multiple data sources and no output schema), the description thoroughly explains what the tool returns (cik, filings, fundamentals, patents, news, LEI) and their formats (e.g., pipeworx URIs, sorted period_end DESC). It also covers limitations (no names, patent soft-fail) and provides sufficient context for the agent to set expectations.

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 reinforces the semantics: type is fixed to 'company', value can be ticker or zero-padded CIK, and names are not supported. It adds practical context but does not introduce entirely new 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 uses specific verbs like 'full cross-source profile' and 'returns' along with concrete examples ('Tell me about X', 'brief me on Tesla'), clearly identifying the tool's purpose as a holistic company information aggregator. It also distinguishes itself from sibling tools like resolve_entity by specifying that names are not supported.

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 'ALWAYS PREFER over chaining single-pack... lookups' for holistic views and instructs to use resolve_entity first if only a name is available. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's mention of 'Delete' is consistent. It adds minor context about pairing but doesn't contradict annotations.

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

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

Three efficient sentences, no wasted words. Action is front-loaded ('Delete a previously stored memory by key').

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 links to siblings. Complete.

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

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

Schema coverage is 100% and the description only restates 'by key'. Baseline of 3 is appropriate since the schema already documents the parameter well.

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

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

The description clearly states the action ('Delete') and the resource ('a previously stored memory by key'). It distinguishes from sibling tools like 'remember' and 'recall' by explicitly pairing with 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?

Provides explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with sibling tools.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds fetching, extraction, and output format details. 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?

Single paragraph, well-structured, front-loaded with main action. Every sentence is useful and no redundancy.

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

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

Given no output schema, description adequately explains input, process, and output format. Use cases provide context. Slightly lacking potential error or edge-case info.

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 3 applies. Description provides minimal additional meaning beyond schema descriptions (e.g., 'site to summarize', 'max link entries').

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

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

Clear verb 'Generate' and resource 'llms.txt file' with specific purpose for AI crawlers. Distinguished from sibling tools as the only one producing this specific file format.

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 concrete use cases (client indexing, personal drafting, competitor auditing). Lacks explicit when-not-to-use or alternatives, but the use cases are comprehensive.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by listing the returned fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying default active-only filtering.

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

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

Two sentences, front-loaded with purpose, no wasted words. Efficiently conveys 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?

For a simple list tool with good annotations and complete schema, the description is complete: it explains purpose, return fields, and usage context. No output schema exists, but return fields are listed in the description.

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

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

Schema coverage is 100%; the description does not add extra information about the include_inactive parameter beyond what the schema provides. Baseline of 3 applies.

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

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

The description clearly states the action (List), the resource (the caller's subscriptions), and the scope (active). It also 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?

Provides explicit guidance on when to use ('review what you're monitoring before adding more or to find an id to cancel'), though it doesn't explicitly state when not to use it.

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

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

Annotations are all false and uninformative, so the description carries the full burden. It richly discloses non-obvious behaviors: a 5-per-identifier daily rate limit, no quota cost, the claim_token return-and-check workflow, and daily team review cycles. 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 longer than average, but every sentence earns its place by adding scoping, behavioral, or operational value. It is front-loaded with the core purpose, then proceeds to usage constraints and workflow details, with no redundant 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?

Despite lacking an output schema, the description clearly states what a call returns (claim_token) and how to use it later. It covers alternatives, scope, parameter guidance, rate limits, token workflow, and post-submission expectations, making the tool fully self-contained for an agent.

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

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

With schema description coverage at 100%, the baseline is 3, but the description adds meaningful usage semantics beyond the schema. It instructs users to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts, and it explains that filing without an account yields a claim_token for later status retrieval. These operational details enhance parameter understanding.

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

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

The description opens with a clear verb and object ('Tell the Pipeworx team') and enumerates the exact feedback categories (bug, feature/data_gap, praise). It also explicitly scopes the tool to Pipeworx connection tools, distinguishing it sharply from the many sibling research and market 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?

It provides precise when-to-use scenarios (wrong/stale data, missing tool, unexpected success) and an explicit exclusion: feedback about tools from other MCP servers should be filed with that server instead. This makes the decision boundary unambiguous, including a fallback heuristic ('Pipeworx tool names are the ones this connection lists').

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: it's derived from CF analytics-engine, no PII, and cached (5min-1h depending on window). This extra transparency goes beyond annotations.

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

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

The description is concise, using a single paragraph with bullet-like enumeration. Every sentence adds value, no filler. It's well-structured and front-loaded with the core purpose.

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

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

Despite no output schema, the description explains return values (top tools, top packs, total call volume) and caching behavior. For a simple read-only tool with one parameter, this is complete and actionable for an AI agent.

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

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

Schema coverage is 100% with one enum parameter 'window'. The description enhances this by explaining that shorter windows surface what's hot now, while longer windows show steady-state demand. This adds semantic value beyond the schema's description.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a recent window, with a specific verb ('returns') and resource ('what other AI agents are calling on Pipeworx'). It distinguishes from sibling tools like 'discover_tools' by focusing on trending/call volume rather than general discovery.

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

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

The description lists three concrete use cases: discovering hot data sources, confirming canonical choices, and checking alignment with agent needs. While it doesn't explicitly state when not to use this tool, the guidance is clear and actionable, earning a 4.

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, etc. The description adds detailed behavioral context (semantic anchor, partition filter, fill check) without contradicting annotations.

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

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

The description is verbose and includes many technical details (e.g., Jaccard similarity threshold, placeholder fraction). While informative, it could be more concise; front-loading is adequate but the length may hinder quick scanning.

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

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

Despite no output schema, the description fully explains the response structure (opportunities[], partition_check, fill_check) and covers edge cases (placeholders filtered, thin_legs). All modes and their behaviors are documented.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema: it clarifies that event accepts slugs or full URLs, gives examples for topic, and explains the implications of each parameter choice.

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

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

The description states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It clearly distinguishes between three modes (trending_scan, event, topic) and differentiates from siblings like polymarket_fill_risk via specific usage notes.

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

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

Explicit guidance on when to use each argument: no args for trending_scan, event for specific market (recommended), topic for cross-event scanning. It also warns when not to trade (if realizable_edge_pp ≤ 0) and suggests an alternative for custom sizing (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?

Annotations already declare readOnlyHint=true, and the description adds extensive behavioral details: five model families with formulas, edge calculation after slippage, Kelly fractions with caps, 24h move warnings, caching at KV level keyed on knobs, and diagnostic output. No contradictions.

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

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

The description is long but front-loaded with the purpose statement. Every sentence provides specific technical detail or behavioral context, earning its place. Could be slightly more concise, but the complexity of the tool justifies the length.

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

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

Despite no output schema, the description fully explains the response structure (by_segment, fed_candidates, _diagnostics) and covers all aspects: models, edge calculation, knobs, caching, and diagnostics. It is complete for a complex tool with 9 parameters.

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

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

Schema coverage is 100% with detailed descriptions. The tool description adds value by explaining the purpose of tradeable-edge knobs (e.g., min_liquidity/max_spread_pp drop opportunities where edge isn't realizable) and the interaction between parameters, beyond the schema's field-level docs.

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 top Polymarket markets for opportunities where Pipeworx data disagrees with market price, and positions it for the 'what should I bet on today' use case. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on discovering opportunities without paging hundreds of markets.

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

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

The description provides clear context on when to use (agents discovering opportunities without paging) and details tradeable-edge knobs. It notes that Fed bets are surfaced but excluded from ranking. However, it does not explicitly mention when not to use or suggest alternative tools, though the purpose is well-covered.

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=false) are consistent. The description adds critical context: reads from daily snapshots, returns tracked/expired/snapshot_dates arrays, explains decay computation on |edge_pp_net|, and discloses limitations like 60-day TTL and daily close data only.

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

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

The description is well-structured with clear sections: purpose, args, response format, limits. While thorough, it is slightly verbose but each sentence adds value.

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

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

With no output schema, the description fully explains the response structure (tracked[], expired[], snapshot_dates[]), covers edge cases like gaps and expired opportunities, and specifies data limitations. It is comprehensive for a tool with two optional parameters.

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

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

Schema coverage is 100%. Description adds context beyond schema: days default 14, max 30 (schema says clamp 2-30), window default '1wk', and explains what 'window family' means. This adds marginal 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 it provides 'edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It distinguishes from sibling tools like polymarket_edges by focusing on historical time-series analysis.

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

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

The description explains when to use this tool: to answer 'how long has this edge existed and is it shrinking?' and contrasts a fresh wide edge with a 3-week-old wide edge. It also mentions limits (60-day TTL) and decay calculation scope, but does not explicitly name alternative tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which the description aligns with. The description adds valuable behavioral context: it walks the order book ladder, returns detailed fill metrics and a verdict, and in basket mode warns about forced directional risk. No contradictions.

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

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

The description is long but well-structured with clear sections (summary, requirements, single-market, basket, usage advice). Information is front-loaded and no sentence is wasted. A minor trim could be possible, but it remains efficient for the complexity.

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

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

Given the tool's complexity (two modes, multiple outputs), the description covers inputs, outputs, risks, and when to use. Despite lacking an output schema, it enumerates return fields for both modes. This provides sufficient context for correct use, especially with the risk warnings.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. However, the description adds significant interpretation: clarifying side defaults in basket mode, explaining size_usd as settlement notional for baskets, and describing how market/event parameters control modes. This goes 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 checks realizable-vs-theoretical edge against live order book depth, with explicit single-market and basket modes. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by specifying that it is a preliminary risk check.

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

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

The description explicitly advises using this tool before acting on polymarket_arbitrage signals or edges trades above $500. It explains when to use each mode and warns about the risks of partial fills and uncapturable overround, providing clear guidance on when not to rely solely on theoretical edge.

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

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

Even with readOnly/idempotent annotations, the description adds substantial behavioral disclosure: matching is keyword/overlap based, compatibility fields can be non-empty even when pairs are returned, unknown legs are never paired, Kalshi fees are not modeled, and spreads are gross not net tradeable. It also defines each compatibility code and temporal alignment semantics.

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 content-dense and well-ordered: purpose, modes, response shape, safety fields, codes, skipped-leg counters, and caveats. A few warnings are repeated for emphasis, but the structure is front-loaded and every paragraph adds operational value.

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

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

With no output schema, the description fully compensates by spelling out the response contents, spread sign convention, safety fields, per-entry flags, temporal alignment semantics, fee disclosure, and skip counters. It even tells the agent which cases land in skipped_unclassified vs low_confidence_pairs.

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

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

The schema already documents all three parameters, but the description adds real meaning: topic values are pre-mapped shortcuts that auto-fetch the matching event, explicit ticker/slug override the mapped side, and both modes run the identical token-overlap matcher. It also provides concrete example 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 opening sentence states exactly what the tool computes: a cross-venue spread between Kalshi and Polymarket for the same resolving question. It is specific enough to stand apart from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description gives clear operational usage: two modes, when to use macro shortcuts versus explicit ticker/slug pairings, and a warning that most pre-mapped topics currently return compatibility warnings so pre-mapped ≠ tradeable. It does not explicitly name sibling alternatives or state when to prefer this over polymarket_arbitrage, but the use context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds useful context: scoping to identifier, listing behavior, and pairing with remember/forget, going beyond annotations.

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

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

Two sentences, front-loaded with main function, no wasted words. Efficient and clear.

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

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

Given simple input schema and no output schema, description covers retrieval, listing, scoping, and pairing. Complete for this 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 parameter. Description adds meaning: explains that omitting key lists all keys and provides context ('scope to identifier'). Adds value beyond schema.

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

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

The description uses specific verbs ('retrieve', 'list') and resource ('saved values'), and distinguishes from siblings 'remember' and 'forget' by explaining its complementary role.

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

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

Explicitly states when to use (retrieve context) and how to list all keys (omit the 'key' argument). Doesn't provide explicit when-not-to-use, but context is clear.

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

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

Description adds context beyond annotations: explains mark_read effect (next call shows newer), mentions idempotent polling behavior, and notes the feed is also accessible via REST. 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?

Concise single paragraph with clear logical flow: purpose, return fields, parameters, behavior, alternatives. Every sentence is informative and well-placed.

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

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

No output schema, but description adequately describes return content (source, citation_uri, payload). Covers all key behaviors: filtering, mark_read, polling, and alternative access. Complete for a read-only 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?

With 100% schema coverage, the description still adds value by explaining how mark_read works, implying default limit of 50, and illustrating filtering usage with examples (e.g., 'sec_8k').

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 pulls fired events from subscription feed, specifying returned fields and filtering options. While specific, it lacks explicit differentiation 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?

Provides explicit guidance: describes when to use (pulling alerts programmatically), notes that polling is fine, and gives an alternative access method (GET endpoint) for scripts/dashboards.

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, non-destructive. The description adds valuable behavioral context: multi-source fan-out, fallback logic, soft-fail on USPTO, return structure with citation URIs, and date format details. No contradictions.

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

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

Description is a single paragraph that is detailed yet efficient, front-loaded with example queries. Each sentence adds value, though slightly dense. Could be trimmed slightly but still good.

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

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

Given no output schema, the description explains the return format (changes[] grouped, total_changes, citation URIs). Covers source behavior and date syntax. Could mention result limits or pagination but not essential.

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

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

Schema coverage is 100%, but description adds significant meaning: explains 'since' format (ISO or relative), suggests '30d' for typical use, defines 'value' as ticker or CIK, and clarifies 'type' is only 'company'. This goes well beyond schema descriptions.

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

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

Description explicitly states the tool provides a 'change feed for a company in the last N days/weeks/months', specifies data sources (SEC EDGAR, GDELT→GNews, USPTO), and distinguishes from sibling tool 'entity_profile' which gives a static profile.

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

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

Provides example queries and clearly states when to use 'entity_profile' instead. Explains fallback behavior and source-specific details (e.g., USPTO soft-fail). Lacks explicit when-not-to-use scenarios but the alternative guidance is strong.

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 idempotent and non-destructive, and the description adds valuable context: key-value scoping by identifier, persistence differences between authenticated and anonymous users (24h). 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?

Five sentences, each earning its place: what, when, how (scoping), persistence, and pairing with siblings. Front-loaded with primary action.

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 2-parameter tool with no output schema, the description covers lifecycle, usage, and behavioral details completely. No gaps.

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

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

Schema coverage is 100%, but the description enhances meaning by providing example key formats ('subject_property') and clarifying the value can be any text, adding practical 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?

The description uses a specific verb ('Save') and resource ('data') with clear examples of use cases (resolved ticker, target address) and distinguishes from sibling tools recall and forget.

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

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

Explicitly states 'Use when you discover something worth carrying forward' and directs to recall for retrieval and forget for deletion, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the bar is lower, but the description adds substantial behavioral context. It discloses internal cascading through multiple lookup endpoints, graceful degradation when GLEIF/OpenFIGI is unavailable, explicit `unresolved` reporting, and the `figi_candidates` ambiguity behavior. This is exactly the kind of context an agent needs beyond structured annotations.

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

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

The description is long and dense, but it is well-organized: examples and purpose first, then supported types and behavioral nuances. Every major block earns its place given the tool's complexity. It is slightly verbose with parenthetical overload, but not to the point of impairing usability.

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 burden of explaining return behavior. It covers resolved identifiers with source labels, explicitly states that unresolvable identifiers appear under `unresolved`, explains `figi_candidates` for ambiguous matches, and documents graceful degradation. This is sufficient for an agent to select and invoke the tool correctly.

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

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

Although schema description coverage is 100%, the description adds significant meaning beyond the schema. It explains that `value` accepts ticker, CIK, ISIN, or company name, covers how ISIN resolves to legal entities, and warns to pass the issuer name exactly as printed rather than the full question noun phrase. This materially improves correct invocation.

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 and resource: "resolve a user-spoken NAME to the canonical/official identifiers other tools require as input." It differentiates the tool from siblings by framing it as the first step when an ID is needed, and even notes it "replaces 2-3 manual lookups." This makes it clear what the tool does and why it exists.

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

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

The description gives explicit when-to-use guidance: "Use FIRST whenever you have a name but need an ID." It also clarifies accepted input forms and warns against passing full noun phrases for bonds. However, it does not explicitly name sibling alternatives or describe when NOT to use this tool, so it stops short of a 5.

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

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

Annotations already declare read-only, idempotent, non-destructive. The description adds behavioral details: it probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, signal density. This provides meaningful context beyond annotations without contradiction.

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

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

The description is two sentences with no waste. The first sentence front-loads the core action (compare AI visibility), and the second adds details, use case, and output structure. Every sentence earns its place.

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

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

The tool has 4 parameters (1 required), no output schema. The description explains the output (ranked list with score, confidence, signal density) and the probing mechanism. It could mention the entity count constraint (2-8) from the schema, but overall it's sufficiently complete for an agent to understand usage and return format.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add parameter-specific meaning beyond what the schema already provides; it only explains the overall process. No extra semantics for models, _apiKey, context, or entities.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using specific verbs and resources. It distinguishes itself from siblings like ai_visibility_check (single entity) and compare_entities (generic) by focusing on competitive AI-marketing audits with ranking and scoring.

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

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

The description gives clear context for use in competitive AI-marketing audits and implies probing multiple entities. It doesn't explicitly state when not to use or mention alternatives like ai_visibility_check for single entities, but the context is sufficient for an agent to decide.

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

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

Annotations already declare safe/read-only behavior. Description adds valuable context about partial failures, timing of bundlephobia, and graceful degradation.

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 usage, then behavior. Some redundancy but overall efficient for the amount of info.

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 2 params, no output schema, and high complexity (multiple APIs, partial failures), description fully covers what the tool does, returns, and edge cases.

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

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

Schema coverage is 100% for both parameters. Description adds only minor details (scoped packages, version defaults), but no contradictory or missing 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 it's a composite check for adding npm packages, covering license, advisories, bundle size, etc. Distinguishes from siblings by being specific to npm and combining deps.dev and bundlephobia.

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 (safety/popularity/size questions) and notes NPM-only in v1, with alternatives for other ecosystems.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. Description adds critical behavioral details: truncation at 200K chars with flag, embedding model (BGE-base-en), windowing (500-char overlapping), similarity measure (cosine), and return includes offsets. No contradictions.

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

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

Concise and well-structured: front-loaded main purpose, then usage guidance, then technical details. Every sentence adds value without redundancy. Efficient communication in four sentences.

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

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

No output schema, but description explains output includes passages with offsets and similarity scores. Covers all key aspects: when to use, what it returns, technical details, and limitations (truncation). Complete for a search tool.

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

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

Input schema has 100% description coverage with clear parameter descriptions. Description adds further context: text max length hint, query examples, and default limit. However, schema already does most of the work; description adds modest 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?

Description states 'semantic search INSIDE a fetched record' with specific verb+resource. Distinguishes from sibling tools like ask_pipeworx_grounded by explaining pairing, showing clear differentiation.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and provides an alternative pattern: pairing with ask_pipeworx_grounded. Gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations indicate it is non-destructive and idempotent. The description adds behavioral context: it evaluates passive aggression and regret probability and gives a biased recommendation toward 'no'. This exceeds annotation baseline.

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

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

Two efficient sentences that convey purpose and key behavioral traits. No wasted words, but could be slightly more structured.

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

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

Given the existence of an output schema (not shown) and full parameter coverage, the description is sufficient for an analysis tool. It covers the main evaluation criteria and recommendation bias.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description does not add additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states it analyzes whether to send an email, evaluating passive aggression and regret probability with a biased recommendation. This is specific and distinct from sibling tools, but no explicit differentiation is provided.

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

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

The description implies usage when uncertain about sending an email, but lacks explicit when-to-use or alternatives among siblings. The context is clear but guidance is only implied.

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

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

The description discloses behavioral traits beyond annotations: requires OAuth, returns subscription ID, delivery constraints (email validation, SMS cap, webhook signing and auto-disable). Annotations are consistent (readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false).

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

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

The description is well-structured: purpose first, then types, then delivery. It is fairly long but every sentence adds value. It could be slightly more concise, but the clarity justifies the length.

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

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

Given the tool's complexity (5 types, 3 delivery options, auth requirements), the description is complete. It covers required prerequisites, type-specific parameters, delivery channel details, and return value (subscription ID). No output schema exists, but the description adequately addresses expected output.

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

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

Schema coverage is 100%, but the description adds significant meaning: for each type, it provides practical examples (e.g., sec_8k with items codes, polymarket_edge with topic). For delivery, it elaborates on SMS verification, email validation, and webhook signing secret. This greatly aids correct parameter usage.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 context on when to use the tool, including the requirement for a Pipeworx OAuth account (anonymous/BYO cannot persist). It also enumerates supported subscription types and delivery channels, giving examples. However, it does not explicitly state when not to use it or mention alternatives beyond the 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. Description adds details about return format and parameter 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?

Description is slightly long but front-loaded with common queries and detailed enough. 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 tool with one optional parameter and no output schema, the description fully explains the return format (category-bucketed example questions with tool calls) and use cases.

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

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

Schema coverage is 100% and the description simply restates the schema's parameter description. No additional meaning is added 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 is the onboarding entry point, returns category-bucketed example questions, and differentiates from siblings by mentioning it teaches how to call meta-tools like ask_pipeworx.

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

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

Explicitly says use this first when you don't know what Pipeworx can do, and provides optional topic filtering. Does not give explicit when-not, but context makes it 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?

Describes ownership enforcement and deactivation behavior beyond annotations. No contradiction with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true).

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

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

Three concise sentences, each adding essential information. Front-loaded with primary purpose.

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

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

Single parameter, no output schema, description fully covers purpose, ownership, and side effects.

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 parameter with description. Description reinforces 'by id' and links to 'subscribe' output. Baseline 3, slight 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?

Clear verb ('cancel') and resource ('subscription by id'). Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

States ownership enforcement ('only cancel your own subscriptions') and explains behavior (deactivation not deletion). Provides clear context for when 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?

The description goes well beyond the readOnlyHint/idempotent annotations by explaining critical behavioral nuances: the meaning of 'could_not_verify' vs. 'unsupported' (check didn't happen vs. no source exists), the presence of verification_error{stage,detail}, and the warning not to show could_not_verify as evidence. It also describes the routing to SEC EDGAR vs. grounded pipeline, giving the agent important expectations about how results are produced.

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

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

The description is longer than average but efficiently front-loads user-facing trigger phrases and provides essential behavioral context. Every sentence contributes value: purpose, routing, return types, error semantics, and rationale. Slightly verbose in the middle but not padded; earns 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?

Despite no output schema, the description fully enumerates possible verdicts, explains the difference between could_not_verify and unsupported, and describes the return payload (value, citation, reasoning). It also covers routing logic and error handling, making the tool's behavior predictable for an agent in varied scenarios.

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

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

Schema coverage is 100% and the schema already describes both parameters well (claim with examples, tolerance_pct with range and purpose). The description does not add parameter-level detail beyond what's in the schema, so it meets the baseline for high coverage without needing to compensate.

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

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

The description clearly identifies the tool's purpose: verifying natural-language factual claims against authoritative sources. It includes multiple trigger phrases ('fact check', 'verify the claim that...') and distinguishes itself from general Q&A or research tools by focusing on claim verification and returning a verdict. This is a specific verb+resource with clear scope.

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

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

The description explicitly states when to use this tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides routing rules for company-financial vs. other factual claims, and notes that the tool 'Replaces 4–6 sequential calls,' reinforcing why it's a better alternative than composing multiple steps. No named alternatives, but the when-to-use is explicit and practical.

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