Fac

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds critical behavioral context: default model (Workers AI Llama-3.3-70b, free), BYO key for Anthropic (cost implications), and explicit return shape (per-model {score, confidence, signals, raw_response} + combined view). No contradiction.

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

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

Four sentences, each carrying essential information. Front-loaded with verb and resource, then return format, then usage notes. No fluff or redundancy. Perfectly concise.

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

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

With 4 parameters, no output schema, and moderate complexity, the description fully covers what the tool does, what it returns, and how to customize. It explains the default behavior, optional Anthropic integration, and disambiguation via 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 description coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining the default model behavior, the cost/model implication of _apiKey, and how 'context' aids disambiguation. This extra guidance justifies a score of 4.

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

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

The description clearly states that the tool probes LLMs to score visibility of a business/product/topic on a 0-100 scale. It uses specific verbs and resources ('probe', 'score visibility') and distinguishes from sibling tools like 'ask_pipeworx' (which answers questions) and 'deep_research' (comprehensive research) by focusing on AI visibility measurement.

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 brand checks, competitive monitoring. It explains when to use optional parameters (_apiKey for Anthropic, context for disambiguation). While it doesn't state when NOT to use, the context is clear enough for an agent to decide.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context: it fills arguments automatically, returns structured answers with stable citation URIs, works on every tier, and is fast. This goes beyond annotations without contradicting them.

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

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

The description is long but information-dense and front-loaded with the key instruction to prefer over web search. It includes examples and alternative tool guidance without fluff. While not terse, every sentence contributes to tool selection and usage.

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

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

Given no output schema, the description explains the return includes structured answers with pipeworx:// citation URIs. It covers broad usage scenarios, gives examples, and clarifies when alternatives are needed. This is outstanding completeness for a tool with no 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?

Schema coverage is 100% with the 'question' parameter and aliases fully documented. The description does not add deeper semantics beyond what the schema provides, but it does reinforce that the input is a natural-language question and gives examples. Baseline 3 is appropriate.

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

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

The description clearly states the tool answers factual questions by routing to structured data sources, and explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research. It lists concrete domains (SEC filings, FDA drug data, etc.) and provides examples, leaving no ambiguity about purpose.

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: prefer this over web search, use as default entry point, and explains when to step up to ask_pipeworx_grounded or deep_research. It also notes breaking-news coverage, providing clear when/why alternatives are better.

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 the experimental edge, live candidate routing status, and that results are compared against the stable router to decide merges. It clarifies 'Falls back to nothing — this IS a full working router,' adding important context about its operational 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 three focused sentences, front-loaded with the beta status, usage guidance, and current state. Every sentence adds relevant information without redundancy, making it efficient and well-structured.

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

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

For a beta variant of a known router, the description covers current behavior, experimental purpose, and the comparison process. It references the identical response shape to ask_pipeworx, so no separate output schema is needed, and it provides enough context for an agent to understand when and why to use it.

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

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

All 6 parameters are aliases for 'question' and are fully documented in the schema (100% coverage). The description adds no additional parameter-level detail, so baseline 3 is appropriate since the schema carries the explanatory burden.

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

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

The description clearly states it is the beta version of ask_pipeworx, an identical universal router with the same 5,566 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by explaining candidate routing improvements and its experimental role.

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

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

Explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing,' providing a clear use case. It also notes that no candidate is currently active, so it matches ask_pipeworx exactly, and names ask_pipeworx as the comparison alternative, giving when/how to use it.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the refusal mechanism with exact refusal_reason values, the evidence quote behavior, and the extra LLM call cost, providing full behavioral transparency without contradicting annotations.

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

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

The description is compact yet comprehensive—covers purpose, process, return shape, refusals, usage guidance, and cost in roughly five sentences without 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?

Given no output schema, the description fully specifies the success return object and refusal variants, covers the tool's internal routing, and situates it against the simpler alternative, making it contextually 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 already documents all six parameters as aliases for the question with 100% coverage. The description adds no new parameter-specific semantics beyond what the schema provides, so 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 clearly states it is a 'hallucination-resistant answer mode' that extracts answers using ONLY what the tool result contains, distinguishing it from sibling ask_pipeworx by its grounded extraction behavior and explicit return format.

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on...' and 'prefer ask_pipeworx for casual lookups', naming the exact alternative and cost tradeoff. This provides clear when-to-use and when-not-to-use guidance.

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

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

The description extensively discloses behavioral traits beyond annotations. It explains fan-out patterns per category, response shapes, resolver contract with confidence levels, news fallback mechanisms, safety short-circuits for low-confidence matches and closed markets, tradeability warnings for wide spreads, and resolution-rule risk. All annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent with the description.

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

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

The description is comprehensive but lengthy (multiple paragraphs). It is well-structured with labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.), which aids readability. However, some redundancy exists (e.g., repeated mention of closed/dead markets) and the sheer length may overwhelm agents. It could be slightly more concise.

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

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

Given the tool's complexity (3 parameters, no output schema, numerous edge cases), the description is thoroughly complete. It covers all aspects: input resolution, fan-out logic, response structure, resolver contract with confidence and alternatives, news fallback, safety mechanisms, liquidity warnings, and cancellation rule parsing. No critical information is missing.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description adds significant value by explaining how the market parameter is resolved (slug, URL, question text), the depth parameter's impact (quick vs thorough fan-out), and the include_raw parameter's trade-off between summary size and full payloads. This goes beyond the schema descriptions.

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

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

The description explicitly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly specifies input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). The tool is well-differentiated from siblings like polymarket_edges and polymarket_edge_tracker.

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

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

The description provides clear usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also includes detailed behavioral guidance including fan-out examples and response shapes. However, it does not explicitly state when not to use this tool versus alternatives.

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

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

Annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) are consistent. The description adds valuable behavioral details: it pulls latest 10-K revenue/net income/cash/debt for companies (with proper fiscal year handling), and FAERS counts/FDA approvals/trial counts for drugs. Also states results are sorted by primary metric and returns paired data with citation URIs.

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

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

The description is somewhat long but front-loaded with common trigger phrases. Every sentence adds value, explaining triggers, entity types, data sources, and output features. Could be slightly shortened but is well-structured.

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

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

Given no output schema, the description explains return value (paired data + citation URIs) and mentions sorting. It covers both entity types with specific metrics. Missing explicit output format but acceptable for a comparison tool with only 2 parameters.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds practical usage details: 'values' expects tickers/CIKs for companies and drug names, with min 2, max 5 items. It also clarifies what metrics are pulled per type, which goes beyond the schema's type enum.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs. It lists specific trigger phrases ('Compare X and Y', 'X vs Y', etc.) and distinguishes between entity types with distinct data sources (SEC EDGAR for companies, FAERS/FDA for drugs). This differentiates it from sibling tools like entity_profile.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' giving clear context for when to use. It does not list explicit exclusions or alternatives beyond sequential lookups, but the guidance is strong and sufficient.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description richly details behavior: decomposition into facets, parallel routing, findings packet with verbatim evidence and citations, explicit gaps[], contradiction scanning, semantic excerpting, and expected latency ranges. It adds far more context than the annotations alone, and no contradiction exists.

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

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

The description is long (several paragraphs) but every sentence adds value: account requirements, not-open-web caveat, usage fits, depth behaviors, citation resolvability, and performance expectations. Information is front-loaded with purpose and prerequisites, though some sentences are dense and could be trimmed for readability.

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

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

Despite no output schema, the description thoroughly specifies what the tool returns (findings packet, evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], hop) and covers edge cases (unanswerable facets, long records, non-structured topics). This is a complex tool, and the description fully equips an agent to understand scope, limitations, and timeout expectations.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful depth semantics: 'standard' re-angles unanswered gaps, 'thorough' chases leads and adds contradictions, and 'quick' is single-hop. It also clarifies the 'question' parameter accepts broad/multi-part natural language, exceeding schema descriptions.

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

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

The description clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' in one call, explicitly distinguishing it from open-web search. It also differentiates from siblings by naming ask_pipeworx for single lookups, making the purpose 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?

Explicit guidance is provided: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It even handles the not-signed-in case with a clear alternative. This fully addresses when to use 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?

Beyond the annotations (readOnlyHint, etc.), the description reveals that the tool returns top-N relevant tools with full schemas and curated examples, ready to call directly, which is critical behavioral context not captured by annotations.

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

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

The description is comprehensive but slightly verbose. It front-loads the core purpose and provides useful details, though some sentences could be merged without losing clarity.

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

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

Given the tool's complexity and lack of output schema, the description fully covers purpose, usage, output content (top-N tools with schemas), and when to use it, leaving no gaps for an AI agent to invoke correctly.

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

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

The input schema covers 100% of parameters with descriptions and aliases. The description reinforces that the query accepts natural language and lists example domains, adding value beyond the schema but not significantly new.

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 'Find tools by describing the data or task' and lists many specific domains, distinguishing it from sibling tools which are about data retrieval or analysis rather than tool discovery.

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

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

The description explicitly instructs 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)', providing clear guidance on when to use this tool versus alternatives.

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

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

Annotations already mark read-only, idempotent, non-destructive. The description adds detailed behavioral context: fans out across multiple sources, returns specific data fields, and mentions the patent sunset in May 2025. No contradictions.

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

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

The description is a single dense paragraph but front-loads examples and the preference rule. Bold type emphasizes key points. It is packed but efficient for the tool's complexity.

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

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

For a complex tool with no output schema, the description details the returned fields (cik, filings with URIs, fundamentals, patents, news, LEI). It could be more precise about fundamentals and news structure, but overall fairly complete.

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

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

Schema coverage is 100% with descriptions. The description reinforces parameter usage with examples (ticker 'AAPL' or CIK) and clarifies that names are not supported, adding value beyond schema.

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

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

The description explicitly states the tool returns a 'full cross-source profile of a US public company in ONE parallel call', provides example queries, and distinguishes it from chaining single-pack lookups and the sibling tool resolve_entity for 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 says 'ALWAYS PREFER over chaining single-pack... when the user asks for a holistic view' and notes names are not supported, directing to use resolve_entity first. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds value by clarifying the output (types of findings) and the include_text parameter behavior. 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?

Two sentences: first defines findings, second gives usage guidance. Every word serves a purpose; no redundancy. Front-loaded with the core purpose.

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

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

No output schema exists, so description must cover return values. It lists finding types but does not detail response structure (e.g., fields, pagination). Adequate but could be more complete for a 6-parameter tool without 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?

Schema description coverage is 100%, so baseline is 3. The description does not add significant new semantics beyond what the schema already provides, merely rephrasing parameter purposes in a narrative.

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 retrieves audit findings for single audits, listing specific types (compliance exceptions, material weaknesses, etc.) and the question it answers. It differentiates from sibling FAC tools by focusing on findings and mentioning query methods.

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

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

The description provides clear guidance: query by report_id or sweep by recipient name/UEI. It answers a specific question ('has this grant recipient had audit findings...'). Alternatives are implied through siblings, though no 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?

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds context about resolving recipient names via an extra call (include_recipients parameter), which is helpful. It does not contradict annotations.

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

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

Two sentences with a clear action verb and an example. Front-loaded with the primary purpose, no fluff.

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

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

Despite having 9 parameters and no output schema, the description explains the output fields (recipient name, state, audit year, major program status) and mentions ranking by dollars. This provides sufficient completeness for a data-listing tool.

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

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

Schema coverage is 100%, so baseline is 3. The description provides an example and summarizes the purpose, which adds context beyond the parameter descriptions. However, it does not detail each parameter individually.

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

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

The description clearly states the tool lists organizations by CFDA number, ranked by dollars expended, with key details. It provides examples and answers a specific question, distinguishing it from sibling tools like fac_search_audits or fac_recipient_audit_history.

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

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

The description implies usage for finding who spends money in a federal program, but does not explicitly state when to use this tool versus alternatives or provide 'when not to use' guidance. No mention of sibling tool 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, idempotentHint, etc.) already indicate safe read behavior. The description adds value by specifying the enrichment content: program details, auditee/auditor info, and findings. 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?

Two sentences with no filler. The first sentence front-loads the action and key outputs; the second succinctly states the core question answered. Every word earns its place.

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

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

The description explains the main returned data (program details, auditee/auditor, findings) but does not clarify the award_limit parameter's impact on the 'full' detail claim. Since no output schema exists, the description should have explicitly addressed the row limit 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?

Input schema provides 100% coverage with descriptions for all three parameters. The description mentions report_id implicitly and award_limit indirectly via 'max federal award rows', but does not add new semantic information beyond the schema.

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

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

The description uses specific verbs ('Fetch', 'enriched') and clearly identifies the resource (audit by report_id). It distinguishes itself from sibling tools like fac_search_audits (which searches across audits) and fac_audit_findings (which returns only findings) by focusing on a single audit's comprehensive details.

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

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

The description implies usage after obtaining a report_id from fac_search_audits, but does not explicitly state when to use this tool vs alternatives like fac_audit_findings or fac_federal_awards_by_program. No 'when not to use' guidance is provided.

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

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

Annotations (readOnlyHint, idempotentHint, etc.) already disclose safety and idempotency. The description adds value by specifying output fields and the growth read, but does not mention data freshness, rate limits, or error handling. Overall, behavioral context is adequate.

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

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

Two sentences plus a concluding line, each purposeful. The first sentence states the core function, the second details output, and the third captures the user's intent. No wasted words.

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

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

Given no output schema, the description compensates by enumerating returned fields (audit year, total federal awards, report_id, oversight agency, FAC acceptance date, spend trend growth). It also notes identification methods. However, it omits details like default years value or state usage, which are in the schema but not reinforced in the text.

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

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

Input schema has 100% description coverage for all 5 parameters, so baseline is 3. The description does not add additional parameter meaning beyond the schema (e.g., it does not explain how 'state' disambiguates names or default for 'years').

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

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

Description clearly states it returns year-by-year single-audit history for one grant recipient, identifies allowed methods (UEI or name), and lists specific output fields. It distinguishes from siblings like fac_search_audits or fac_get_audit by focusing on multi-year trends for a single recipient.

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

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

The description implies usage when you need multi-year audit history for a specific recipient via UEI or name. It provides good context but lacks explicit when-not-to-use or reference to sibling alternatives, leaving the agent to infer based on sibling names.

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, establishing it as a safe, non-destructive read operation. The description adds value by explaining the query semantics (substring matching, examples) and the overarching purpose, going beyond 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 three sentences with no wasted words. It front-loads the action and resource, then briefly describes output and purpose. Every sentence is meaningful and earns its place.

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

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

Given 11 parameters (0 required) and no output schema, the description is remarkably complete. It explains the domain (US single audits, Uniform Guidance), search methods, return fields, and the core question it answers. Pagination and ordering are covered by the schema, so no gaps exist.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reiterates key parameters (name, UEI, EIN, state, audit year, min_total_expended) but does not add significant new meaning beyond what the schema already provides. It provides context about 'single audit' but no extra parameter-level details.

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 'Search', the resource 'US single audits' filed with the Federal Audit Clearinghouse, and specifies the search criteria (auditee name, UEI, EIN, state, audit year, min federal dollars). It also lists the return fields and the question it answers, distinguishing it from sibling tools that focus on findings, programs, or individual audit details.

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

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

The description implies usage for searching audits but does not explicitly contrast with sibling tools like fac_audit_findings or fac_federal_awards_by_program. It lacks when-not-to-use guidance or alternative recommendations, though the context of 'single audits' helps narrow the scope.

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

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

Annotations already declare destructiveHint=true, and the description confirms the destructive nature ('Delete'). It adds context about use cases for clearing data, which is useful but does not detail behavior like whether deletion succeeds if key is missing. Since annotations cover the main behavioral trait, this is a strong score.

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

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

Two sentences: first states purpose, second provides usage guidance and pairing. No unnecessary words; every sentence adds value. Front-loaded with the action.

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

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

For a simple tool with one parameter and no output schema, the description adequately covers purpose and usage. It could mention handling of missing keys, but given the simplicity and annotation coverage, it is mostly complete.

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

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

Schema coverage is 100% with the 'key' parameter already described as 'Memory key to delete'. The description does not add additional semantic meaning or constraints beyond what is in the schema, so 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 'Delete a previously stored memory by key,' which is a specific verb-resource pair that clearly distinguishes it from sibling tools like 'remember' (store) and 'recall' (retrieve).

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

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

Explicitly states when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also suggests pairing with 'remember' and 'recall', providing clear context for usage.

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 explains the fetch, extract, and emit steps, and specifies the output format ('single text blob ready to drop at site-root/llms.txt'). 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 succinct with no wasted words: the first sentence states the core purpose, the middle explains the process, and the final sentence lists use cases. All sentences earn their place.

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

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

For a tool with two simple parameters, no output schema, and comprehensive annotations, the description fully covers purpose, process, output format, and use cases, leaving no important 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 both parameters described adequately. The description adds context for the URL parameter (e.g., 'Full URL' or 'specific landing page') and reinforces the default/max for max_links, but does not provide essential new information beyond the schema.

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

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

The description uses a specific verb ('generate') and resource ('llms.txt file'), clearly states the purpose of creating a standard file for AI crawlers, and distinguishes itself from sibling tools like 'ai_visibility_check' or 'scan_competitor_ai_presence'.

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, personal project, auditing competitors) but does not mention when not to use or name alternative tools like 'scan_competitor_ai_presence' as alternatives.

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

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

Annotations already declare readOnlyHint=true, so the description adds value by listing returned fields. However, it doesn't mention potential pagination limits, but the context is moderate.

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?

Extremely concise (two sentences) with no filler. Key information is front-loaded.

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

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

Fully covers purpose, usage, and return fields despite no output schema. The low complexity (one optional param) is well-handled.

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

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

Schema coverage is 100% with a clear description for include_inactive. The description adds no additional meaning 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?

Clearly states it lists active subscriptions and specifies exact return fields (id, type, etc.), distinguishing it from siblings like subscribe and unsubscribe.

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

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

Explicitly advises to use this tool to review current subscriptions before adding more or to find an id for cancellation, providing clear when-to-use guidance and implicit 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?

Beyond the annotations (all false, offering no safety hints), the description discloses return behavior (claim_token), rate limiting (5 per identifier per day), quota impact (free, doesn't count against tool-call quota), and operational facts (digests read daily, signal affects roadmap). This adds substantial context not available in schema or 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, front-loaded with the primary purpose. Every sentence contributes operational or usage detail (exclusions, claim token, rate limits, quota). It could be improved with structured bullets for scannability, but there is no filler or redundancy.

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

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

For a 4-parameter tool with no output schema and a nested object, the description fully covers triggering conditions, exclusions, payload guidance, claim_token flow, rate limits, and account behavior. No critical gaps remain; it is complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with detailed parameter descriptions, so baseline is 3. The description adds value by explaining the claim_token workflow ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and implicitly reinforcing type semantics (bug, feature, data_gap, praise), raising it above 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 uses a specific verb 'Tell' and resource 'Pipeworx team', clearly stating the tool's purpose of reporting broken/missing/surprisingly-good things. It distinguishes from siblings by scoping strictly to Pipeworx connection tools and enumerating exact use cases (bug, feature/data_gap, praise), unlike any sibling tool.

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

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

Explicitly states when to use ('Use when a tool returns wrong/stale data...') and when not to ('ONLY for tools served by this Pipeworx connection'), with a direct alternative ('file it with that server instead'). Also provides content guidance ('Describe the issue in terms of Pipeworx tools/packs') and claim_token follow-up workflow.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true. The description adds valuable context: 'derived from CF analytics-engine, no PII' and 'Cached 5min-1h depending on window'. This goes beyond the annotations by explaining data source and caching behavior.

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

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

The description is three sentences, front-loaded with the core return data, followed by use cases and technical notes. Every sentence adds value with no redundancy, making it highly efficient for an AI agent to parse.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, use cases, caching, and data semantics. It could be more complete by explicitly stating the output format (e.g., 'returns JSON object'), but the current detail is sufficient for an agent to understand expectations.

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

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

Schema coverage is 100% with a good enum description. The description adds extra meaning by explaining window semantics: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides strategic guidance beyond schema details.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a window. It uniquely identifies the resource as 'what other AI agents are calling on Pipeworx', distinguishing it from sibling tools like 'discover_tools' and 'ask_pipeworx' by emphasizing its self-aggregating trending signal.

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?

Three specific use cases are listed: discovering hot data sources, confirming canonical tool choice, and assessing alignment. While no explicit exclusions or alternative tool references are given, the context clearly implies when to use this tool over query-based siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds behavioral context: it performs monotonicity checks, partition_sum checks, uses Jaccard similarity thresholds, filters placeholder slugs, and includes a fill check against live CLOB depth. It also warns not to trade when realizable edge <= 0. 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 well-structured: it starts with overall purpose, then details each mode with bullet points. It is front-loaded with the core function. However, it is somewhat verbose with technical details (e.g., Jaccard threshold, placeholder filter, fill check) that could be condensed. Still, every sentence adds value.

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

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

Despite lacking an output schema, the description explains the response format: opportunities array with fields (gap_pp, suggested_trade, reasoning, monotonicity violation context) and partition_check object in event mode. It also covers fill check behavior and cross-event similarity filtering. It references polymarket_fill_risk for custom sizing, providing a complete picture.

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

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

The schema has 100% description coverage for its two parameters (event and topic). The description adds substantial meaning: event mode walks child markets, checks ordering, and computes partition_check; topic mode searches related events, flattens markets, and runs comparator. It also explains semantic anchor (Jaccard threshold) and partition filter, which are not in the schema.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes: trending scan (no args), single-event mode (event parameter), and cross-event mode (topic parameter). This specificity differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description explicitly explains when to use each invocation pattern: no args for trending scan, event for a specific market, topic for cross-event scanning. It provides recommendations (event recommended for specific markets) and explains the benefit of cross-event mode. However, it does not explicitly state when NOT to use this tool, such as for single-outcome markets or when real-time data is not needed.

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 traits beyond the annotations: it details the three model families, caching at KV level with 1h TTL, filtering logic, diagnostic output, and tradeable-edge knobs. It complements the annotations (readOnlyHint, idempotentHint) 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 lengthy but well-structured, starting with the core purpose and then diving into segments, parameters, output structure, and caching. It is front-loaded with the most important information. Minor length could be trimmed, but every section adds value.

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

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

Given the complexity (9 parameters, no output schema, nested output structure), the description is exceptionally complete. It explains the response segments, diagnostics for empty results, caching behavior, and tradeable-edge knobs. An agent can fully understand what the tool does and how to interpret results.

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

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

All 9 parameters are described in the input schema (100% coverage), and the description adds significant context for parameters like slippage_pp (explaining Polymarket fees and depth), min_liquidity (walk the book), and min_partition_leg_kelly (why min_kelly doesn't apply to partitions). This goes beyond the schema descriptions.

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

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

The description clearly states it scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. This distinguishes it from other tools like polymarket_arbitrage, and it explicitly says it is built for 'what should I bet on today' discovery.

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

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

The description provides contextual usage guidance ('Built for what should I bet on today'), and explains the tool helps discover opportunities without paging hundreds of markets. While it does not explicitly list when NOT to use this tool versus alternatives, the context is sufficient for an agent to understand its intended use case.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds rich behavioral detail: response structure with tracked[], expired[], snapshot_dates[], trend categories (new|widening|stable|decaying), decay_pp_per_day sign convention, and limitations (snapshot TTL, daily closes). This goes far beyond what annotations provide.

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

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

The description is fairly long but well-structured: front-loaded purpose, then response format, then limitations. Every sentence adds value; the LIMITS section is particularly useful. Could be slightly shorter but still efficient.

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

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

With no output schema, the description fully documents the response structure (tracked[], expired[], snapshot_dates[], including subfields like first_seen, trend, decay_pp_per_day, lifespan_days). It also explains the computation of trend and decay. For a tool with 2 optional params, this is very complete.

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

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

Schema coverage is 100% with adequate descriptions. The description adds nuance: default days=14 with clamp 2-30, default window='1wk', and explains window as 'snapshot family'. This adds meaning beyond the schema.

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

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

The description states a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers the exact question 'how long has this edge existed and is it shrinking?' and distinguishes from sibling polymarket_edges by focusing on time-series and decay.

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

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

The description gives clear context on when to use: for evaluating edge persistence and comparing fresh vs old edges. It includes limitations like snapshot TTL and decay computation method, but does not explicitly mention specific alternative tools or when not to use. However, the context implies that for current single-edges, use polymarket_edges instead.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds significant behavioral context: it walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage, etc.), and describes how basket mode handles legs. No contradiction with annotations.

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

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

The description is well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET) and uses capitalization for emphasis. However, it is somewhat verbose; some sentences could be trimmed without losing meaning. It earns its length for the complexity it covers but is not as concise as it could be.

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

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

Given that there is no output schema, the description thoroughly covers return fields for both modes, explains the verdict field, and warns about partial fills and directional risk. It addresses the dominant loss mode and provides sufficient detail for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema documents all parameters. The description adds value by explaining the dual interpretation of 'size_usd' (spend vs. target proceeds) and the default side logic for baskets. This goes beyond schema descriptions, justifying 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 the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It uses specific verbs and resource references, and implicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by positioning itself as a prerequisite check.

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

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

The description explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overround not capturable, partial fills leading to directional risk), providing clear context and exclusions.

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

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

Annotations already indicate idempotent, read-only, non-destructive behavior. The description adds substantial behavioral context: two modes, response structure (leg-by-leg prices, spread array), safety fields (compatibility_warning conditions, temporal_alignment, skipped counters), and the warning that most shortcuts return warnings. No contradiction with annotations.

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

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

The description is dense but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence provides meaningful information without redundancy. It is front-loaded with the core purpose and efficiently uses formatting (capitalization, parenthetical examples) to aid readability.

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

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

Given the tool has 3 optional parameters, no required fields, and no output schema, the description comprehensively covers the expected response format, safety fields, and edge cases (compatibility warnings, temporal alignment). The agent has sufficient information to interpret results and decide when to trust the spread. No gaps identified.

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

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

Input schema has 100% parameter coverage with descriptions and examples. The description adds value by explaining the interaction between topic and explicit parameters (topic overrides explicit sides), and elaborates on the safety fields in the response. However, the schema descriptions already cover the parameter meanings well, so the description's added value is moderate.

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 cross-venue spread comparison tool between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit tickers) and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue arbitrage. The verb 'spread' and resource description are 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 explains when to use topic mode vs explicit ticker mode and warns that most pre-mapped topics return compatibility warnings, guiding the agent to check safety fields. It implies when not to use (when compatibility_warning fires), but does not explicitly recommend alternative tools for single-venue arbitrage, such as polymarket_arbitrage from the siblings list.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds scoping detail ('Scoped to your identifier') and clarifies that omitting the key lists all saved keys, going beyond bare annotations.

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

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

Three sentences covering purpose, examples, scoping, and pairing with siblings. No redundant words; front-loaded with the main action.

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

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

Lacks explicit return format description but adequately covers retrieval and listing behavior given no output schema. The use cases provide enough context for an agent to understand expected outputs.

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

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

Schema coverage is 100% and the description adds value by explaining behavior when the parameter is omitted (list all keys), which is not inferred from 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 function: retrieve a value saved via remember, or list all keys when the argument is omitted. It uses specific verbs and distinguishes from sibling tools 'remember' and 'forget' by mentioning pairing.

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

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

Provides explicit use cases (looking up stored context like ticker, address, notes) and explains when to omit the key argument. Does not explicitly exclude scenarios, but the context is clear enough for an agent to decide when to use it.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds behavioral details like the mark_read flag effect and that polls work, which complements 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?

Three sentences: first states purpose, second details content, third explains features and alternatives. Concise with no unnecessary words.

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

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

All 5 optional parameters are covered, return fields are described (source, citation_uri, payload), and behavioral nuances (mark_read, polling) are explained. No output schema needed; the description is complete for agent invocation.

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

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

Despite 100% schema coverage, the description adds meaningful context: explains mark_read behavior, gives an example for the type parameter ('sec_8k'), and clarifies that since expects an ISO timestamp. This goes beyond the schema definitions.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifies key returned fields (source, citation_uri, payload), and lists filtering options. It is specific and distinguishes from sibling tools.

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

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

The description mentions polling works fine and provides an alternative direct-API endpoint for scripts/dashboards, guiding when to use this tool vs. alternatives. However, it does not explicitly state when not to use it.

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

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

Annotations (readOnlyHint, idempotentHint) are consistent. The description adds detailed behavioral context: fans out to multiple sources, explains GDELT→GNews fallback, notes USPTO soft-fail, and describes output structure with citation URIs. No contradictions.

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

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

The description is somewhat long but well-structured, front-loading example queries. Every sentence adds value, though minor redundancy could be trimmed.

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

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

Given the complexity (multiple sources, fallbacks, parameter options, output structure), the description is fully complete. It explains the fallback, date formats, output grouped by source, and alternative tool. No output schema, so the description covers return values adequately.

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

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

Schema coverage is 100%. The description adds meaning beyond schema: explains 'since' formats (ISO/relative) with examples, clarifies 'type' is only 'company', and gives examples for 'value' (ticker or CIK). Also recommends default 'since' values.

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

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

The description states the tool provides a change feed (SEC filings, news, patents) for a company within a time window, using concrete user queries as examples. It explicitly distinguishes from sibling entity_profile, which is for static profiles.

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 via example queries ('What's new with X') and explicitly directs users to entity_profile for static profiles. It also recommends typical 'since' values like '30d'.

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

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

Describes storage as key-value scoped by identifier, persistence for authenticated users vs 24h for anonymous, beyond idempotent annotation.

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

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

Three sentences, front-loaded purpose, 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?

Complete for a simple memory tool: covers purpose, usage, persistence, pairing, and scoping.

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

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

Schema covers 100% of parameters; description adds specific key/value examples enriching 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?

Clear verb 'save' with resource 'data' and context 'across conversation/sessions'. Distinguishes from sibling tools recall/forget by mentioning pairing.

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

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

Explicitly advises use when discovering worth to carry forward. Mentions pairing with recall/forget, though could explicitly state when not to use.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds rich behavioral detail: cascading internal lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` reporting, source labeling for identifiers, and ISIN-to-LEI mapping. No contradiction with annotations.

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

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

The description is dense and front-loaded with natural-language examples and a clear directive, but it is a long, unbroken paragraph. Every sentence carries useful information, yet splitting into bullets or sections would improve scannability without losing content.

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

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

This is a complex tool with no output schema, but the description thoroughly compensates. It covers return values (source-labeled identifiers, unresolved field), ownership hierarchy, fallback behavior across sources, and the internal cascade that replaces multiple manual lookups. Both entity types are fully described, making the tool complete enough for an agent to use correctly.

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

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

Since schema coverage is 100%, the baseline is 3. The description adds meaningful value beyond the schema by showing example formats (ticker, CIK, ISIN, name), clarifying that ISIN resolves to the legal entity issuing the security, and specifying that drug queries return RxCUI, ingredient, brand, and a citation.

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 resolves user-spoken names to canonical identifiers and explicitly names supported types (company and drug). It distinguishes itself from siblings like compare_entities and entity_profile by focusing on name-to-ID resolution as the first step in a workflow.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It does not mention when not to use it or name alternative tools, but the use case is unambiguously framed and practical.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that the tool returns a ranked list with score, confidence, and signal density, and that it internally calls ai_visibility_check—valuable context 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 three sentences, contains no fluff, and front-loads the primary action. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description explains what is returned (ranked list with score, confidence, signal density). With 4 parameters all described and a clear behavioral explanation, the description is fully complete for an AI agent to understand and use the tool correctly.

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

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

With 100% schema coverage, the baseline is 3. The description adds that the first entity is treated as the 'subject' and the rest as competitors, clarifies that models can be omitted for workers-ai, and explains how context disambiguates names. This goes beyond the schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes itself from sibling tools (e.g., ai_visibility_check) by its side-by-side comparative nature.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example question, implying when to use. It does not explicitly state when not to use or list alternatives, but the context is sufficient for an AI agent to judge applicability.

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 behavior: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed list will contain timed-out sources. This goes beyond the annotations.

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

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

The description is relatively long but well-organized: it starts with the core purpose, then lists use cases, return contents, limitations, and edge cases. Every sentence adds value, though it could be slightly more concise.

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

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

Given no output schema, the description thoroughly explains the return format: summary block (with specific fields), per-advisory detail, links, and alternative versions. It covers NPM-only scope, partial failure behavior, and timing. Very complete for a complex composite tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds that scoped packages (e.g., @types/node) are accepted, and version defaults to latest when omitted. This adds useful nuance beyond the schema.

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

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

The description uses a specific verb+resource ('scan_dependency') and clearly states it is a composite check for 'should I add this npm package', covering license, advisories, version history, bundle size, etc. It distinguishes itself from sibling tools by being a one-call composite for npm packages.

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

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

Explicitly states when to use: 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. It also notes the NPM ecosystem limitation in v1 and mentions partial failure behavior. No explicit exclusions for other use cases, but context is clear.

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

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

Annotations already indicate readOnlyHint, idempotentHint, etc. The description adds valuable technical details: uses BGE-base-en embeddings + cosine over 500-char windows, caps at 200K chars with truncation flag. 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 concise, using around 100 words in a single paragraph. It front-loads the purpose and each sentence adds value—no filler. The structure is efficient and 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?

Despite lacking an output schema, the description explains the return format: 'top-N passages with character offsets and similarity scores'. It covers input constraints (truncation), embedding details, and typical usage, providing a complete picture for a tool with 3 simple parameters.

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

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

Schema description coverage is 100%, so baseline 3. The description enhances by providing examples for the query parameter, clarifying default limit (5) and range (1-20), and noting the max characters for text. This adds meaningful context beyond schema.

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

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

The description clearly states it performs semantic search inside a fetched record, using a specific verb 'semantic search' and resource 'inside a fetched record'. It distinguishes from siblings by explicitly stating the use case (when a record is too large for the prompt) and naming the complementary tool ask_pipeworx_grounded.

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

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

The description provides clear guidance on when to use: 'Use when the record is too big to cram into the prompt'. It also explains the pairing with ask_pipeworx_grounded for grounding over passages. However, it does not explicitly state when not to use or list alternatives.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=true, etc.), the description adds significant behavioral context: it returns subscription id, webhook secret only once, SMS cap of 10/day, webhook auto-disabled after 10 failures, and the requirement for phone verification. No contradictions with annotations.

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

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

The description is long but each sentence carries important information. It is well-structured with separate sections for supported types and delivery channels. A minor deduction for verbosity, but no waste.

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

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

Given the complexity (3 params, nested objects, multiple types, no output schema), the description is remarkably complete. It covers all subscription types, their params, delivery options, limitations, and return value details. No missing critical context.

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

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

The schema description coverage is 100%, and the description adds extensive meaning beyond the schema: concrete examples for each type's params, constraints on delivery options (phone must be verified, webhook https only, SMS cap). This greatly aids parameter understanding.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It lists supported types and their parameters, and delivery channels, distinguishing itself from siblings 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 and notes that anonymous/BYO cannot persist subscriptions. It provides guidance on when to use each subscription type (e.g., sec_8k for officer changes). It lacks explicit alternatives but implies usage context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it returns example questions with exact tool+argument shapes from the live catalog, and that the tool serves as an onboarding entry point.

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 main purpose. It is slightly long but every sentence adds value, covering usage, return format, and parameter guidance.

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

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

Given the tool's simplicity (1 optional parameter, no output schema), the description is complete: it explains when to use, what it returns, and how to focus via topic. It fully compensates for the lack of 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 has 100% coverage for the single 'topic' parameter. The description adds meaning by listing example values (e.g., 'finance', 'pharma') and explaining that omitting the parameter gives a cross-category spread, which is beyond what the schema provides.

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

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

The description clearly states the tool is the onboarding entry point, returning category-bucketed example questions. It uses specific verbs like 'returns' and distinguishes from siblings by positioning it as the first tool to use when the agent doesn't know Pipeworx's capabilities.

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

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

The description explicitly advises using this tool 'FIRST when you do not yet know what Pipeworx can do' and provides guidance on the optional topic parameter. It does not explicitly list when not to use, but the context is clear.

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

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

Adds behavioral details beyond annotations: ownership enforced, deactivation not deletion, historical events persist. Annotations indicate mutation and idempotency; description aligns and enriches.

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, action first. Every sentence adds value with no redundancy.

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

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

For a one-param tool with good annotations, description fully covers behavioral context (ownership, soft delete) and connects to sibling tool recent_alerts.

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 clear description of 'id' as subscription uuid from subscribe. Description adds that it's returned by subscribe, but no further parameter details needed.

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

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

Description clearly states 'Cancel a subscription by id' with specific verb and resource. It distinguishes from siblings like subscribe (create), list_subscriptions (list), and recent_alerts (historical events) by mentioning deactivation behavior.

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?

Describes when to use: canceling own subscription. Mentions ownership enforcement and relationship to recent_alerts. Lacks explicit when-not or direct sibling comparisons, but context is clear.

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

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

Beyond the readOnly/openWorld annotations, the description adds critical behavioral context: the two-track routing, the specific verdict set, and the important caveat that could_not_verify means the check did not happen and must not be shown as evidence. It also clarifies the difference between could_not_verify and unsupported, which is not implied by the annotations.

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

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

The description is long but tightly structured: examples lead in, then usage trigger, routing logic, return summary, and a clear caller warning. Every sentence carries distinct, non-redundant information, and the critical warning is highlighted with IMPORTANT.

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?

This is a complex tool with two processing paths, a rich verdict set, and error semantics. Without an output schema, the description fully compensates by explaining verdict meanings, citation format, and the behavior of could_not_verify versus unsupported. It gives an agent everything needed to select and invoke correctly.

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

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

The schema covers 100% of parameters, but the description adds meaningful semantics beyond it. For tolerance_pct it explains overrides the claim-implied tolerance, recommends 1–2 for hallucination detection, and notes the default cap of 5. Claim examples also illustrate the expected input format, which the schema only partially conveys.

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 explicit natural-language examples ("Is it true that…", "fact check") and states it performs "natural-language claim verification against authoritative sources". It clearly distinguishes this from sibling query tools by covering both company-financial claims via the structured SEC EDGAR path and any other factual claim via the grounded pipeline.

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?

"Use whenever the agent needs to check whether something a user said is factually correct" gives an explicit trigger condition. It also explains the routing rule for financial vs. other claims and notes it replaces 4–6 sequential calls, making it clear this is the consolidated tool for claim verification without needing alternatives.

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