Trade Intel

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds behavioral context: default model is free, Anthropic requires BYO key and is passed through directly, and return format includes score, confidence, signals, and raw_response per model.

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 with the most important information first. Every sentence adds value, with no redundancy or filler.

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

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

Despite lacking an output schema, the description explains the return structure and all parameters. It covers purpose, usage, models, and practical context (free vs. paid, use cases), making it fully complete 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?

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining default model behavior, key passthrough, and disambiguation help for the context parameter, exceeding the schema alone.

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

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

The description clearly states the tool's purpose: probing LLMs for brand visibility and scoring it 0-100 per model. It distinguishes itself from sibling tools by focusing on visibility scoring rather than general Q&A or research.

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

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

The description provides explicit use cases (AI-marketing audits, pre-launch checks, competitive monitoring) and explains the default vs. keyed model options. It does not explicitly mention when not to use or list alternatives, but the context is clear enough.

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

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

Beyond the read-only/idempotent annotations, the description discloses core runtime behavior: it routes to one of 5,798 tools, fills tool arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. This gives an agent an accurate model of how invocation and outputs behave.

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 instruction ('PREFER OVER WEB SEARCH'), then gives scope, mechanism, trigger phrases, and concrete examples. Each sentence serves a distinct purpose and there is no filler.

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

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

For a one-required-parameter open-ended router, the description covers what the tool accepts, why to use it, how routing works, and what the response includes. The annotations cover safety/idempotency, and the lack of an output schema is compensated by the explicit statement that answers are structured and carry citation URIs.

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

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

The input schema already describes all six parameters as aliases for the natural-language question, so schema coverage is 100%. The description's examples illustrate acceptable queries but add no new parameter semantics beyond what the schema states.

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

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

The description clearly identifies ask_pipeworx as a natural-language router that selects among thousands of verified sources and returns a structured, cited answer. It is explicit about the domain it covers and contrasts itself with web search, but it does not mention the sibling tools ask_pipeworx_beta or ask_pipeworx_grounded, so differentiation from siblings is incomplete.

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?

Strong guidance: 'PREFER OVER WEB SEARCH', explicit trigger phrases, examples, and 'START HERE for most questions' tell an agent when to use it. However, there is no explicit when-not clause distinguishing it from the sibling Pipeworx tools, so it falls short of full alternatives coverage.

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 safety annotations, the description discloses important behavioral traits: it is an experimental edge with no fallback, it is a full working router, and candidate routing improvements may be live during testing. It also gives a precise current status (no active candidate as of 2026-07-26), helping the agent understand exactly what this tool will do.

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 and well-structured, opening with the core purpose and then adding critical usage context, current status, and the no-fallback caveat. Every sentence provides distinct value without repetition or unnecessary filler.

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

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

For a tool with no output schema, the description supplies enough context for correct invocation: identical behavior to ask_pipeworx, current experimental state, and no fallback. The response shape is described only by reference to ask_pipeworx, which is acceptable if the sibling definition is available, but slightly less self-contained.

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

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

Schema coverage is 100%, with all parameters documented as aliases for the required 'question' field. The description does not add parameter-level detail, but the schema already carries the full meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with the same tool set, arguments, and response shape. It differentiates itself from the stable ask_pipeworx by emphasizing experimental routing improvements, though it does not explicitly distinguish itself from the ask_pipeworx_grounded sibling.

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

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

The description explicitly says to use it exactly like ask_pipeworx when the newest routing is desired, and notes that results are compared against the stable router. It also states that currently no candidate is active, so behavior matches ask_pipeworx, giving useful situational guidance, though it does not discuss when to avoid it or choose ask_pipeworx_grounded.

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

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

Annotations already mark readOnly/openWorld/idempotent, but the description adds substantial behavior beyond that: the refusal protocol with five enumerated refusal_reason values, the exact success return shape (answer, evidence as verbatim quote, confidence, source, fetched_at), the guarantee of extraction 'using ONLY what the tool result contains', and the extra LLM call cost. No contradiction with the annotations — the readOnlyHint aligns with the fetch-and-read nature.

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 efficiently structured: purpose → mechanism → return contract → usage guidance → cost tradeoff. Every sentence earns its place and the primary purpose is front-loaded. It runs slightly long, but for a tool with refusal semantics and a return contract this complexity is largely justified.

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

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

There is no output schema, so the description must document the return contract — and it does so thoroughly for both the success and refusal paths, including the exhaustive refusal_reason enum. Given the high complexity (routing across 5,798 tools, extraction constraint, refusal modes) the description is complete: an agent knows what it returns, when to call it, when not to, and what behavioral guarantees to expect.

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

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

Schema description coverage is 100%: the single required 'question' parameter is fully documented with all six aliases (query, q, prompt, text, input). The description adds no parameter-level meaning beyond the schema, which is appropriate since the schema already carries the burden. Baseline 3 applies.

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

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

The description opens with a specific, meaningful framing — 'Hallucination-resistant answer mode for high-stakes reads' — and states the exact mechanism (same routing as ask_pipeworx, then extracts the answer using ONLY what the tool result contains). It distinguishes itself from the sibling ask_pipeworx by naming it directly and contrasting the casual vs. high-stakes use case. An agent can tell this tool apart from its siblings immediately.

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 (financial verdicts, legal claims, medical lookups, public statements), and explicit when-not-to guidance ('prefer ask_pipeworx for casual lookups'), including the cost tradeoff of one extra LLM call. This is the ideal level of routing clarity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description goes far beyond these by detailing response shapes, resolver contract (market_match_confidence and alternatives), parent event extraction, news fallback fields, safety mechanisms (low-confidence short-circuit, closed market handling, wide spread warnings), and resolution-rule risk. This provides deep behavioral transparency that complements the 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 long but well-organized with clear sections (classifiers, fan-out examples, response shapes, resolver contract, etc.) and front-loaded with the core purpose. Every sentence provides actionable information, though some detail (e.g., extensive fan-out examples) could be slightly compressed without loss of meaning. Overall, it efficiently conveys complex behavior.

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

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

For a tool with 3 parameters and no output schema, the description is exceptionally complete. It covers input formats, behavior variations (depth), error handling (low-confidence, closed markets, illiquid spreads), response structure, and even resolution-rule risk. The agent has all necessary context to use this tool correctly and understand its limitations.

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

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

Input schema coverage is 100% with descriptions for all three parameters. The description adds significant value by providing concrete examples for the 'market' parameter (slug, URL, question text), explaining the default behavior of 'depth' (default thorough), and detailing the use case for 'include_raw' (when to pass true for full payloads). This goes beyond schema descriptions to guide agent decisions.

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

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

The description starts with a clear verb+resource combination ('Research a Polymarket bet') and immediately distinguishes the tool from siblings by specifying that it pulls 'Pipeworx data' in one call. It provides specific input types (slug, URL, question text) and explains the workflow (resolves, classifies, fans out). This strongly differentiates it from sibling tools like polymarket_edges or polymarket_arbitrage.

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 lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It provides extensive examples of classifiers and fan-out logic, giving agents clear context for when to invoke this tool. However, it does not explicitly state when NOT to use it (e.g., alternatives for simpler queries), which slightly prevents a top score.

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

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

Adds significant detail beyond annotations: describes data sources (SEC EDGAR/XBRL, FAERS), specific metrics (revenue, net income, cash, debt, adverse events, trial counts), sorting by primary metric, and citation URIs. All consistent with readOnly, openWorld, and idempotent hints.

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 efficiently conveys purpose, usage, behavior, and examples. Front-loaded with common queries, no redundant 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?

Returns are partially described (metrics, sorted, citations) but no output schema. For a tool with two modes, the description covers key aspects like fiscal year handling and preferred usage, though exact data shape for each type could be more explicit.

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 has clear descriptions for type and values (with enum and min/max items). Description adds concrete examples for both company tickers and drug names, enhancing usability. With 100% schema coverage, this is a valuable addition.

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

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

The description clearly defines the tool as performing side-by-side comparisons of 2–5 companies or drugs, with examples like 'compare X and Y' and 'head to head'. It distinguishes from siblings like entity_profile by recommending preference over sequential lookups.

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

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

Explicitly states when to use: for comparisons of 2–5 entities, and when to prefer over sequential lookups. Provides example queries and explains behavior for company vs drug types.

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

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

The description goes far beyond the readOnly/openWorld/idempotent annotations. It discloses account and payment requirements, the response format (findings packet with verbatim evidence, confidence, source, fetched_at, citation), the explicit gaps[] for unanswered facets (never invented), contradictions[] available in standard/thorough, semantic excerpting behavior, and expected latency (15-60s, up to ~90s). It also explains the conditional nature of citation_uri, ensuring the agent knows citations are only present when they are fetchable. This provides substantial behavioral context beyond annotations.

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

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

The description is long but information-dense, and the most critical operational facts (account required, free tier, paid thorough, alternative tool) are front-loaded. Every sentence contributes useful behavior or usage detail. It could be tightened slightly, but for a tool with this complexity, the length is justified and the structure is 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 there is no output schema, the description must convey return expectations, and it does so thoroughly: findings packet structure, citations, gaps[], contradictions[], hop field, semantic excerpting, and timing. It also covers prerequisites (sign-in, paid plan), alternatives, and edge cases (citations only when fetchable). An agent has enough context to select and confidently invoke this tool without an output schema.

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

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

The input schema already covers 100% of parameters with detailed descriptions, including the depth enum's quick/standard/thorough semantics. The description adds usage context (e.g., broad questions are appropriate) and reiterates that thorough requires a paid plan, but that information is also present in the schema. Since schema_description_coverage is 100%, a baseline of 3 is appropriate; the description does not materially extend parameter-level 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 begins with a clear statement of what the tool does: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources ... in ONE call'. It names the resource (structured data sources), the action (multi-source research with decomposition and parallel routing), and explicitly contrasts it with 'open-web search'. It further distinguishes itself by naming the sibling tool ask_pipeworx as the alternative for single lookups, so an agent can easily differentiate them.

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

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

The description gives explicit 'when to use' guidance: 'Best for broad/multi-part questions over structured data' and contrasts with 'For a single lookup use ask_pipeworx instead'. It also states when not to use the tool: 'If you are not signed in, use ask_pipeworx instead — it works on every tier'. This is highly actionable guidance that names an alternative and the condition that selects it.

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

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

Annotations already confirm readOnlyHint=true and destructiveHint=false. The description adds that it returns top-N relevant tools with names, descriptions, and full schemas ready to call directly, revealing useful behavior beyond annotations.

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

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

The description is well-structured and front-loaded with the purpose. It lists many domain examples and ends with the crucial usage instruction. Slightly verbose but every sentence adds value; could be shorter but still effective.

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

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

Given no output schema, the description explains what is returned (top-N tools with names, descriptions, schemas). Parameter count and sibling list are well-covered. The description is complete enough for a discovery tool with high annotation coverage.

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

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

Schema coverage is 100% with all 6 parameters documented. The description mentions accepted aliases but does not add significant new meaning beyond the schema. Baseline score of 3 is appropriate given full schema coverage.

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

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

The description clearly states the tool finds tools by describing data or task, listing many specific domains (SEC filings, financials, FDA drugs, etc.). It uses specific verb+resource and distinguishes from sibling tools by being the discovery entry point.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Also mentions when to browse, search, look up, providing clear context for when to use this tool vs 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 declare read-only, open-world, idempotent, and non-destructive behavior, and the description richly supplements these: it reveals parallel fanout, soft-failure for patents, expected-empty fda_products, resolved:false handling for private companies, and the semantics of sources_used/sources_failed. This goes far beyond the annotations and prevents misinterpretation of empty sections as bugs.

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

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

The description is long but densely packed with behaviorally relevant details, organized by output section and with key guidance front-loaded ('ALWAYS PREFER'). Each sentence adds information; nothing is filler. It is not maximally concise due to the large number of edge-case disclosures, but those are necessary for correct invocation of such a broad tool.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: it enumerates every output field, notes maximum counts, explains URI formats, documents fallback chains, and clarifies expected empty and soft-fail conditions. An agent can invoke the tool and correctly interpret its results without external documentation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful detail: it clarifies that type 'company' and 'ticker' are interchangeable, that value accepts ticker, zero-padded CIK, or name, and that names resolve via SEC EDGAR. It also communicates the resolved:false outcome for private companies, which is beyond the schema. The only reason it is not 5 is that much of this information also appears in the schema.

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

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

The description opens with concrete user phrasings and immediately defines the core purpose: 'full cross-source profile of a US public company in ONE parallel call.' It clearly states the resource (a company) and the action (build a profile), and distinguishes itself by explicitly warning against chaining single-pack lookups for holistic questions. This is a precise, differentiated purpose statement.

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

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

The description gives an explicit selection rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also explains what inputs are acceptable, how names resolve, and what happens for private companies. This tells an agent exactly when and how to invoke the tool versus alternatives.

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

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

Annotations already indicate destructiveHint=true, so the description's 'Delete' is consistent. It adds context about previous storage but no further behavioral details beyond what annotations provide.

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

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

Two concise sentences, front-loaded with action. No extraneous 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?

Well-suited for a simple destroy-by-key tool. Covers purpose, usage triggers, and sibling pairing. No output schema needed.

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

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

Schema coverage is 100% with a description for 'key'. The description does not add additional meaning beyond the schema's 'Memory key to delete'.

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

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

The description clearly states the verb 'Delete' and the resource 'memory by key'. It distinguishes from siblings by naming 'remember' and 'recall'.

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

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

Provides explicit when-to-use scenarios: stale context, task completion, clearing sensitive data. Mentions pairing with siblings but lacks explicit when-not-to-use.

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

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

The annotation set (readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false) already assures safe, non-destructive behavior. The description adds valuable behavioral details: fetching the page, extracting title/description/key links, and outputting standard llms.txt markdown. 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 three sentences, front-loaded with the main action, and contains no filler. Every sentence adds distinct value: purpose, process, and use cases.

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

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

Despite no output schema, the description fully explains the return format (single text blob ready for site-root/llms.txt) and the extraction process. With annotations covering safety and idempotency, the description is complete for this simple tool.

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

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

Schema description coverage is 100%, so the description adds no extra parameter meaning beyond the schema. The description briefly restates the URL purpose and defaults for max_links, but this is already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action (generate), the resource (llms.txt file for any URL), and the purpose for AI crawlers. It distinguishes this tool from siblings by focusing on a specific output format and use case, with no overlap evident in sibling tool names.

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 lists three concrete use cases (client indexing, own project drafting, competitor auditing), providing clear context for when to use. It does not, however, mention alternatives or when not to use it, preventing a perfect score.

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

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

Discloses return fields (id, type, params, created_at, last_fired_at, fire_count) and default active-only behavior. Annotations already declare readOnly, openWorld, idempotent, non-destructive, so the description adds value by specifying output structure and 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, no wasted words. The first sentence covers purpose and output, the second provides usage guidance. Front-loaded with key information.

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

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

Given the tool's simplicity (one optional boolean, no output schema), the description fully covers purpose, output structure, default behavior, and usage context. 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%, baseline 3. The description adds context about the parameter 'include_inactive' by linking it to 'active subscriptions' default, making the semantics clearer than the schema alone.

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

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

The description clearly identifies the verb 'list' and the resource 'subscriptions' with scope 'the caller's active'. It distinguishes from sibling tools like 'subscribe' and 'unsubscribe' by focusing on listing existing subscriptions.

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

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

Explicitly states when to use: 'review what you're monitoring before adding more' and 'find an id to cancel'. Provides clear context for usage, though it does not explicitly state when not to use.

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

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

Annotations have all hints false, so the description carries the burden. It discloses that filing returns a claim_token without an account, that the token can be used later to read resolution status, that there is a rate limit of 5/day, that it is free and doesn't count against quota, and that the team reads digests daily. 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?

Although the description is longer than average, every sentence earns its place: use cases, exclusions, token workflow, rate limit, and quota exemption. The information is front-loaded with the core purpose and organized logically, making it easy to scan for key decisions.

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

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

The description covers all necessary context: the exact scope (only this Pipeworx connection), the nature of feedback (bug vs feature vs praise), the return behavior (claim_token) despite no output schema, and operational constraints (rate limit, free usage). This makes it complete for the tool's complexity.

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

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

Schema description coverage is 100%: each of the four parameters (type, context, message, claim_token) has detailed descriptions, including enum meanings and token format. The tool description adds only marginal context (e.g., claim_token workflow) beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Tell') and resource ('Pipeworx team'), and clearly enumerates the feedback categories (broken, missing, needs to exist). It distinguishes itself from sibling tools like ask_pipeworx and discover_tools by being the dedicated channel for reporting issues about Pipeworx tools themselves.

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 (bug, feature/data_gap, praise) and a clear exclusion: do NOT report tools from other MCP servers, file with that server instead. Also instructs agents to describe issues in terms of Pipeworx tools/packs and not paste end-user prompts, which is actionable usage guidance.

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

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

Annotations already cover readOnly, openWorld, idempotent, non-destructive. Description adds caching behavior (5min-1h), data source (CF analytics-engine), and no PII. Adds context beyond annotations.

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

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

Very concise; uses bullet points for use cases, no fluff. Every sentence adds essential information.

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

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

For a simple read-only query tool with one optional parameter and no output schema, description fully explains return values (top tools, packs, volume), data source, and caching. 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% with enum description. Description adds nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' Adds meaning 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?

Describes exactly what the tool does: returns top tools, packs, and call volume over a window. Specific verb 'returns' and clear resource 'trending usage on Pipeworx'. Distinguishes from siblings like discover_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?

Lists three explicit use cases (discovering hot data sources, confirming canonical tool, aligning use case). Provides context for when it's useful, though doesn't explicitly exclude when not to use or name 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?

Adds significant details beyond annotations: trending scan covers top ~200 markets, semantic anchor with Jaccard similarity >=0.30, partition filter for placeholder slugs, fill check comparing theoretical vs realizable edge. 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?

Long but well-structured: purpose summary, then mode breakdown, then technical filters, then output spec, then fill check reference. Some redundancy but mostly essential for a complex tool.

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

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

Complete given no output schema: describes response fields (opportunities[] with gap_pp, suggested_trade, reasoning, etc.), fill check logic, and edge cases (placeholders, low similarity). References sibling tool for custom sizing.

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 enriches parameters with contexts: event slug vs full URL, topic seed question, and explains internal behavior for each mode (child market walking, cross-event flooding).

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

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

Clearly states it finds arbitrage opportunities via monotonicity and partition-sum checks. Explains three modes (no args, event, topic) and distinguishes from sibling tools like polymarket_fill_risk.

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

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

Explicitly tells when to use each mode: no args for trending scan, event for specific market (recommended), topic for cross-event scan. Mentions alternatives like polymarket_fill_risk for custom sizing.

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

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

The description extensively discloses behavioral aspects beyond annotations: model families, data sources (FRED, GDELT, FRED log-returns, GDELT article-volume ratio), caveats (fed_candidates unreliability), caching behavior (1h KV), and edge metrics (edge_pp_net, kelly_fraction, 24h move warning). Annotations (readOnly, idempotent, non-destructive) are consistent.

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

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

The description is verbose but well-structured, starting with purpose, then segment details, edge metrics, knobs, and response format. Every sentence adds value, but some detail could be streamlined. Overall, it is appropriately sized given tool complexity.

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

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

The description compensates for the lack of an output schema by detailing the response structure (by_segment, edge fields, diagnostics, fed_candidates). It explains caching and all knobs thoroughly. An agent has sufficient information to understand expected outputs and behaviors.

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

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

Despite 100% schema coverage, the description adds rich semantics to each parameter. For example, min_liquidity describes the effect 'drop thin-book opportunities where executing the edge would walk the book past breakeven', and min_partition_leg_kelly explains why the knob exists and how it differs from min_kelly. This goes well beyond baseline.

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

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

The description explicitly states the tool scans Polymarket markets for edges where Pipeworx data disagrees with market price, and it distinguishes itself from sibling tools (e.g., polymarket_arbitrage) by its specific focus on Pipeworx-derived signals. The three output segments are clearly defined, making the tool's purpose unambiguous.

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

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

The description is tailored for the use case 'what should I bet on today' and explains how the tool avoids paging hundreds of markets. While it does not explicitly contrast with siblings, the detailed explanation of when to use each segment and the knobs provides clear contextual guidance for the agent.

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 annotations, detailing response structure (tracked[], expired[], snapshot_dates[]), computation of decay metrics, and limitations (60-day TTL, daily close data). Annotations already indicate safe read-only behavior, but the description adds rich behavioral context without contradiction.

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

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

The description is dense and informative, front-loading the purpose and then systematically detailing the response. While it is somewhat lengthy (150+ words), every sentence adds value, and the structure is 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 the lack of an output schema, the description thoroughly explains all return fields, metrics, and limitations. Parameters are fully covered, and the tool's complexity is adequately addressed, making the description complete 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%, so baseline is 3. The description adds minor clarifications (defaults and clamp values) that align with the schema but does not significantly enhance understanding beyond what the schema already provides.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question about how long an edge has existed and whether it's shrinking. It uses specific verbs and resources, and distinguishes itself from sibling tools like polymarket_edges by focusing on 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 the tool (to assess edge history and decay) and implies when not to use it by highlighting the difference between fresh and old edges. However, it does not explicitly list alternative tools or provide direct 'when not to use' guidance, though the sibling context offers some differentiation.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) already indicate safe, read-only behavior. Description adds specifics: walks the ladder, returns verdict (clean|degraded|cannot_fill), warns about forced_directional_risk and thin_legs. No contradiction. Value added beyond annotations is substantial but not maximal.

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 lengthy (200+ words) covering two modes and detailed warnings. While information is valuable, it could be more concise. Front-loading the key purpose is good, but overall verbosity prevents a higher score.

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

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

No output schema, so description must fully explain return values for both modes. It enumerates top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, and basket-specific fields like theoretical_sum, capture_ratio, profit_usd, thin_legs, etc. This is complete for the tool's complexity.

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

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

Schema coverage 100% means description doesn't need to compensate heavily. However, description adds context: side has auto-detection for basket, size_usd has different interpretation for basket vs single-market, and clarifies requirement of either market or event. This meaningful addition earns a 4.

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

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

Clearly states it performs a realizable-vs-theoretical edge check against live order-book depth. Distinguishes between single-market and basket modes, and specifies it checks fill risk before arbitrage actions. This differentiates from siblings 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?

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains consequences of partial fills converting arb into directional risk, providing clear when-to-use and when-not-to 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 destructiveHint=false, so the description does the critical work of disclosing behavioral caveats. It discloses that Kalshi fees are not modeled and all spreads are gross, that pairing_unverified is always set, that temporal_alignment null does not mean aligned, and that unknown metric/match legs are never paired. This goes well beyond the annotations and greatly reduces mis-invocation risk.

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 every major block earns its place by explaining modes, response fields, compatibility codes, skipped legs, temporal interpretation, and fee caveats. It is front-loaded with the core purpose and uses clear labels like TWO MODES and RESPONSE, though it could be slightly tightened around repeated temporal-alignment warnings.

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

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

There is no output schema, so the description carries the full burden of documenting return values, and it does so thoroughly: leg-by-leg prices, spread[].top_spreads_pp, compatibility_warning and compatibility_codes, per-entry flags, skipped_cross_type/subtype counters, temporal_alignment, and fees_note. For a complex cross-venue tool, this is unusually complete and leaves an agent with a reliable mental model of what will come back and what to check.

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

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

Input schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains that both modes run the identical token-overlap matcher, that explicit parameters override the topic-mapped side, and how the pre-mapped topic list behaves. This helps the agent understand parameter interactions rather than just param formats.

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 directly defines the tool's function: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It also clearly distinguishes itself from siblings by focusing on the Kalshi–Polymarket comparison and by describing two concrete modes ('topic' and explicit ticker/slug), so an agent can tell what it is and what resource it acts on.

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

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

The description gives explicit guidance on when to use each mode: pre-mapped 'topic' shortcuts versus explicit custom pairings, and it includes strong cautionary advice like 'pre-mapped ≠ tradeable' and 'most pre-mapped topics return compatibility_warning today.' It does not name alternative sibling tools, but it provides clear situational and safety-based usage direction.

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

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

Adds behavioral details beyond annotations: scoping to identifier, listing all keys when omitted. 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?

Three concise sentences with no filler; each sentence adds value: function, examples, scope and pairing.

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

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

Fully covers retrieval behavior, scope, and relationship to other tools; no gaps given simplicity and annotations.

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

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

Schema already describes parameters (100% coverage); description reinforces meaning of omitting key.

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

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

Clearly states it retrieves a saved value or lists all keys, differentiating from siblings 'remember' and 'forget'.

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

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

Explicitly says when to use (look up stored context) and provides examples; mentions scoping and companion 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?

Description adds value by explaining mark_read behavior and polling, but contradicts annotations (readOnlyHint=true vs. mark_read mutation). Leaves behavioral ambiguity.

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, front-loaded sentences: purpose, return fields, filter options, mark_read, and alternative endpoint. No wasted words.

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

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

No output schema; description adequately covers return values (source, citation_uri, payload). All 5 parameters explained. Alternative endpoint mentioned.

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

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

Adds examples for type ('sec_8k') and clarifies mark_read and since. Schema covers all parameters; description enhances understanding without redundancy.

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

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

Description clearly states 'Pull fired events from your subscription feed' with specific verb and resource. It distinguishes from siblings like list_subscriptions by focusing on alert events.

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 context that polls work and mentions an HTTP alternative. Does not explicitly contrast with siblings or specify when not to use.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds value by detailing the multi-source fan-out (SEC EDGAR, GDELT/GNews, USPTO), rate-limiting fallback, and soft-fail for patents. It also mentions return format (changes[], total_changes, citations). This is strong behavioral context, though it omits potential pagination or result limits.

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

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

The description is a single dense paragraph but well-organized: starts with example queries, then explains functionality and fallbacks, then parameter details, then comparison with sibling. It is concise (~170 words) and avoids redundancy, though bullet points could slightly 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?

Given no output schema, the description adequately describes the return structure (changes[] grouped by source, total_changes, citations). It covers key behavioral aspects (sources, fallbacks, soft-fails) and parameter usage. It does not mention default 'since' or result limits, but these are not critical for completeness given the tool's straightforward purpose.

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

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

Schema coverage is 100%, so base parameter descriptions are present. The description enriches them with example values for 'since' (ISO date and relative shorthand like '7d', '30d', '3m', '1y'), notes that 'type' is limited to 'company', and clarifies that 'value' accepts ticker or CIK. This adds practical guidance beyond the schema alone.

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

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

The description clearly states it provides a change feed for a company in the last N days/weeks/months, with concrete example queries. It distinguishes itself from the sibling tool entity_profile, which is for static profiles. The verb 'change feed' plus resource 'company' is specific and unambiguous.

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

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

The description explicitly provides example queries and an alternative tool: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also explains when to choose this tool over others, including fallback behavior (GDELT→GNews) and parameter hints like 'Use "30d" or "1m" for typical monitoring.'

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 idempotent and not destructive. Description adds key behavioral details: scoping by identifier, persistence for authenticated users vs 24-hour retention for anonymous sessions, and key-value storage mechanism.

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, each adding unique information: purpose, usage, storage details, retention, complementary tools. 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?

Simple tool with full schema coverage and annotations. Description explains storage behavior, scoping, and complementary tools, making it complete 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?

Schema has 100% coverage with descriptions for key and value. Description does not add new parameter details beyond stating key-value pair, so baseline of 3 applies.

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

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

The description clearly states the tool's purpose: save key-value data for later reuse across sessions. It provides specific examples like resolved ticker, target address, user preference, distinguishing it from sibling tools recall and forget.

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

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

Explicitly states when to use: when discovering something worth carrying forward. Mentions pairing with recall and forget. Could be improved by noting when not to use, but current guidance 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?

The description goes well beyond the annotations (readOnly, openWorld, idempotent, non-destructive). It details the cascading internal lookup behavior, graceful degradation if GLEIF or OpenFIGI is unavailable, and the handling of multiple matches (returns figi_candidates instead of asserting). It also discloses that each identifier is labelled with its source and that unresolvable identifiers are explicitly listed under 'unresolved'. This is rich behavioral context that informs an agent's expectations.

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

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

The description is long but well-structured, starting with example queries and the core purpose, then diving into type-specific details. Every paragraph adds necessary context given the tool's complexity (two entity types, multiple data sources, edge cases). While it could be slightly more concise, the density is justified by the tool's functionality, and the front-loading of purpose and usage is effective.

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

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

For a tool with two required params, no output schema, and moderate complexity, the description covers all necessary aspects: purpose, when to use, behavioral traits, parameter details, and edge cases (graceful degradation, multiple matches, non-equity instruments). An agent has enough information to call it correctly without additional context. The description even specifies what the tool returns (identifier mappings, candidates, unresolved) despite the lack of an output schema.

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

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

The description significantly enriches the schema. For the 'type' param, it explains the two enum values ('company' and 'drug') and their respective data sources. For 'value', it provides detailed instructions on acceptable formats (ticker, CIK, ISIN, name) and a critical caution: do not pass trailing security-class words for bonds. Even though the schema already describes both parameters, the description adds essential nuances that prevent misuse, fully compensating for any schema gaps.

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 precise purpose: resolving a user-spoken name to canonical/official identifiers needed by other tools. It opens with example queries (ticker, CIK, LEI, RxCUI) and a clear verb-resource framing. It distinguishes itself from sibling tools by positioning as the required first step for name-to-ID conversion, which none of the listed siblings (e.g., entity_profile, compare_entities) cover.

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

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

Explicit guidance is given: 'Use FIRST whenever you have a name but need an ID.' It also explains what input format to pass (entity name only, not full noun phrase) with a concrete example for bonds. While it does not name specific alternative tools, the 'use first' directive and the rationale that it replaces 2-3 manual lookups make the usage context unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds value by explaining the process (probes each entity, ranks by score) and return fields (score, confidence, signal density). Also notes the first entity is treated as subject for narrative.

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

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

Every sentence is purposeful. The description is front-loaded with purpose, followed by usage context, and parameter clarification. No redundancy or fluff.

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

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

Even without an output schema, the description fully explains what the tool returns (ranked list with score, confidence, signal density per entity). Combined with 100% schema coverage and thorough annotations, the description is complete for the tool's complexity.

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

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

Schema coverage is 100%. Description adds meaning beyond schema: for 'entities', notes first entry is subject and rest competitors; for 'context', explains it disambiguates common names; for '_apiKey', mentions it's passed to api.anthropic.com per probe. This enriches the schema.

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

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

Description clearly states the tool compares AI visibility across multiple entities side-by-side, uses ai_visibility_check, and produces a ranked list. This distinguishes it from siblings like ai_visibility_check (single entity) and compare_entities (generic).

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 it is useful for competitive AI-marketing audits and gives an example query. However, it does not explicitly mention when not to use or compare with alternatives like ai_visibility_check or compare_entities.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds beyond: composite nature (two external services), timing details (5-30s for first bundlephobia measurement), and failure handling (sources_failed list). No contradiction.

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

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

The description is front-loaded with the main purpose and use case, then details output and limitations. While slightly lengthy, every sentence adds information; no filler. Structure is logical.

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 external sources, partial failures, no output schema), the description covers the return block structure, links, and alternative versions. It provides sufficient context for an agent to understand what the tool returns and its behavior.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value by clarifying accepted scoped package names and default version behavior, which are not in the schema. This justifies a score above 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 clearly states it's a composite check for evaluating whether to add an npm package, covering license, advisories, version history, and bundle size. It distinguishes itself from sibling tools by being specific to npm package evaluation, with no direct overlap.

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 specifies when to use: when an agent asks about safety, popularity, size, or cost of adding a package. Also provides limitations: NPM-only in v1, directs to deps.dev for other ecosystems, and mentions graceful degradation on partial failures.

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 safe read-only, idempotent behavior. The description adds substantial behavioral detail: uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, a 200K char limit with truncation and flagging, and that every passage includes an offset for verification. This goes well beyond what annotations provide.

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

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

The description is a single, well-structured paragraph that front-loads the core purpose. Every sentence adds value: it explains what the tool does, when to use it, technical details, limitations, and pairing with another tool. No wasted words.

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

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

Despite having no output schema, the description explains return values (passages with offsets and similarity scores). It covers the cap, truncation behavior, and embedding technique. It also describes how to combine with another tool for grounded answers. For a simple semantic search tool, this is 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 description coverage is 100%, but the description enhances understanding by providing concrete examples for the 'query' parameter (e.g., 'supply-chain risk') and confirming the default for 'limit'. It adds context that the 'text' parameter is the already-fetched record, which is not explicit in the schema.

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

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

The description clearly states that the tool performs semantic search inside a fetched record. It specifies the verb ('search'), the resource ('text inside a record'), and the scope ('semantic search'). It distinguishes itself by stating when to use it (when record is too large) and mentions a sibling tool for grounding.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt' and explains that it saves context by returning only relevant passages. It also pairs with ask_pipeworx_grounded, providing a clear alternative workflow. This gives explicit guidance on when to use the tool.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false, but the description adds crucial behavior: requires OAuth, creates a persistent subscription, returns an ID, details delivery channel limitations (10/day SMS cap, webhook auto-disable after 10 failures), and mentions webhook signing secret. No contradictions with annotations.

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

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

The description is well-structured with clear sections (supported types, delivery channels) and efficient use of text. It is slightly long but each sentence adds value; could be slightly tightened but remains 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 the tool's complexity (multiple subscription types, delivery options, prerequisites, and limitations), the description is remarkably complete. It covers prerequisites (OAuth), type-specific parameters, delivery channels with constraints (SMS cap, webhook auto-disable), and return value (subscription id). No output schema exists, but the return value is described explicitly.

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

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

Schema coverage is 100%, but the description adds substantial meaning: explains enum values with examples (e.g., poltmarket_edge topic:'fed'), provides parameter structure for each type (e.g., sec_8k items), and clarifies webhook delivery details (HMAC signing, secret return). This goes well beyond the schema's brief descriptions.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This specifies the verb (create), resource (subscription), and outcome (returns id), distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description explicitly requires a Pipeworx OAuth account, lists supported subscription types with examples, and describes delivery channels. While it doesn't explicitly state when not to use, the context is clear enough to differentiate from other tools like recent_alerts (for pulling) or unsubscribe (for removal).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context about being an onboarding entry point that returns structured example questions and can be called with optional topic. No contradiction.

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

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

The description is informative and well-structured with examples, but it is relatively long (multiple sentences). It could be slightly more concise, but the length is justified by the need to explain the tool's purpose as an onboarding entry point.

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

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

Given the rich annotations, single optional parameter, and no output schema, the description is complete. It explains the return structure (category-bucketed examples), usage patterns, and when to invoke the tool first.

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

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

Schema coverage is 100% with description of the optional topic parameter. Description adds examples of topic values and clarifies that omitting gives a cross-category spread, providing extra usage context beyond the schema.

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

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

The description clearly states this is an onboarding tool that returns category-bucketed example questions with exact tool and argument shapes. It distinguishes itself from siblings like 'ask_pipeworx' by being the 'FIRST' entry point for users who don't know what Pipeworx can do.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call with no arguments for full spread or with 'topic' for focus. 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that it returns bilateral imports, exports, top commodities, and exchange rates, which is useful but does not reveal additional behavioral traits beyond what annotations imply.

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

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

The description is two sentences, front-loaded with the purpose, and includes essential context without any fluff.

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

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

Given that an output schema exists and annotations cover safety, the description provides a good overview of inputs and outputs. It could mention default year behavior, but the schema already covers that. 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 coverage is 100% with descriptions for all 4 parameters. The description adds example country codes and defaults, but these are also present in the schema's examples array. The description provides marginal added value.

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

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

The description clearly states the tool compares trade flows between two countries and lists returned data (imports, exports, top commodities, exchange rates). It distinguishes from sibling tools like trade_country_profile and trade_macro_dashboard by focusing on bilateral 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 provides examples of country codes but does not explicitly state when to use this tool versus alternatives or when not to use it. The context is clear but lacks exclusion criteria.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the description's role is reduced. It adds that the tool returns top 10 partners and commodities, but does not disclose additional behavioral traits like data freshness or pagination. This is adequate but not beyond what annotations imply.

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

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

Two sentences with examples, no extraneous text. The core action and parameters are front-loaded, making it easy to scan.

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

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

Given the simple parameter set (2 params, no enums, no nested objects) and the presence of an output schema, the description fully explains what the tool does and what it returns. No gaps remain for a standard 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%, with both 'year' and 'country_code' described. The description adds value by listing example country codes and clarifying the output's structure (top 10 partners/commodities), which goes beyond the schema to aid selection and interpretation.

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

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

The description clearly states the tool retrieves a country's trade snapshot, specifically the top 10 import/export partners and top 10 commodities. It distinguishes itself from sibling tools like 'trade_bilateral_analysis' and 'trade_macro_dashboard' by focusing on a concise snapshot.

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 examples of country codes and notes the optional year parameter with a default, guiding use. It lacks explicit contrast with alternative trade tools, but the 'snapshot' phrasing implies a quick overview, which is sufficient context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by listing the data blocks included and explicitly guaranteeing that bilateral figures are absent. It does not mention rate limits, but the _blsKey parameter description in the schema covers the keyless cap, so the gap is minor.

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

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

Two sentences with zero filler. The first sentence front-loads the dashboard's scope and contents; the second sentence explicitly excludes bilateral data and points to alternatives. Every clause contributes meaningful information.

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

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

With no required parameters, an output schema present, and annotations covering safety and open-world behavior, the description fully orients an agent: what the tool covers, what it does not cover, and which alternative tool to use. No critical information is missing for correct invocation.

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

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

Schema coverage is 100%, with both _fredKey and _blsKey adequately described as gateway-injected keys with explanations of their purpose. The tool description itself does not need to add parameter-level detail; the baseline score of 3 applies.

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

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

The description names a specific action ('Check') and a specific resource ('US trade indicators'), enumerating the exact series covered (customs duty revenue, Treasury exchange rates, import/export price indices, maritime port disruptions, FRED macro block). It also explicitly states what is not included ('Bilateral figures are NOT here'), clearly distinguishing it from related trade tools.

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

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

The description provides explicit context for when to use this tool (US aggregate trade indicators) and when not to use it (bilateral trade figures), naming the exact alternative tools to call instead: census_trade_balance or census_trade_trends. This leaves no ambiguity about selection.

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

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

Annotations indicate destructiveHint=false and idempotentHint=true. The description confirms non-destructive behavior ('deactivated not deleted') and adds ownership context. No contradiction, but description adds modest value beyond annotations.

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

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

Two concise sentences conveying purpose and key behavioral details. No filler or redundant 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 one-parameter tool with no output schema and adequate annotations, the description covers ownership, behavior, and downstream availability (recent_alerts). Complete given the tool's simplicity.

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

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

The single 'id' parameter is fully described in schema (100% coverage). The description repeats the schema's purpose but adds no additional semantic detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the action 'Cancel a subscription by id' with the resource and mechanism. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying cancellation.

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 ownership enforcement ('you can only cancel your own subscriptions') clarifies when to use. Also explains the behavioral effect (deactivation, not deletion) and links to recent_alerts. No explicit alternative given, but sufficient for typical use.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses meaningful behavior: return verdict values, grounded vs structured paths, citation format, reasoning, and the precise distinction between could_not_verify and unsupported. It also explains that could_not_verify carries verification_error and must not be interpreted as evidence, which is critical runtime context.

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

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

The description is longer than typical but well-structured: examples first, then when-to-use, then routing, return values, and caller warnings. It is front-loaded and every sentence adds operational detail. Slight redundancy remains (the list of natural-language phrases could be shorter), but it is not bloated.

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

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

Given the tool's complexity (dual routing, verdict categories, error semantics), the description is remarkably complete. Parameters are fully covered, return values and citation format are described in prose, and caller-level caveats are included. The lack of an output schema is mitigated by the explicit verdict enumeration and explanation of verification_error.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds value by explaining tolerance_pct semantics ('Overrides the tolerance implied by the claim wording', 'set 1–2 for hallucination detection') and providing realistic example values for claim. This exceeds the baseline but does not fully compensate for lack of enums or a formal output schema.

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

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

The description opens with concrete natural-language examples ('Is it true that…', 'fact check') and states the core function: 'natural-language claim verification against authoritative sources'. It clearly differentiates from siblings like ask_pipeworx by specifying the dual-path behavior (SEC EDGAR for company-financial claims, grounded pipeline otherwise) and noting it replaces 4–6 sequential calls.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and distinguishes the two routing paths (company-financial vs any other factual claim). It also provides a clear 'IMPORTANT for callers' warning about could_not_verify, but it does not explicitly name sibling tools as alternatives or state a when-not-to-use condition beyond the general scope.

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