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 readOnly/idempotent/openWorld, so the description's added behavior—routing, argument filling, returning structured answers with stable pipeworx:// citation URIs—is contextual. It also discloses it works even when web search could answer, clarifying its scope. 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 front-loads the most important directive and organizes content into domains, trigger phrases, examples, and alternatives. Every sentence contributes; however, it could be tightened by removing the duplicated mention of citations.

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 what the tool returns (structured answer with citations), when to use it, and when to use alternatives. With no output schema, this is sufficient; the six examples and trigger phrases cover the required single parameter.

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 and aliases for the question parameter, so the baseline is 3. The description adds value by modeling natural-language inputs with six concrete examples and explaining that it accepts factual questions in plain language.

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 an explicit directive ('PREFER OVER WEB SEARCH') and enumerates concrete domains (SEC filings, FDA data, FRED/BLS, etc.). It states the verb 'routes' and resource: 5,798 tools across 1,517 sources, and differentiates from siblings such as ask_pipeworx_grounded and deep_research.

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

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

It explicitly says to prefer this over web search for specific question types and provides trigger phrases ('what is', 'look up', 'get the latest') plus example queries. It then names alternatives: ask_pipeworx_grounded for grounded answers with citations and deep_research for broad multi-part questions.

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, openWorld, and non-destructive; the description adds meaningful context beyond them: candidate routing improvements are enabled live under test, no candidate is currently active (retired 2026-07-26), so behavior matches ask_pipeworx exactly right now. The clarification 'Falls back to nothing — this IS a full working router, just the experimental edge' prevents the common misconception that a beta tool is a stub. 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?

Four sentences, each earning its place: identity/anchor to ask_pipeworx, current test status, usage direction, and the 'full working router' correction. The concrete details (5,798 tools, 2026-07-26 date) add credibility rather than bloat. Slightly long, but every sentence contributes distinct information.

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

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

For a beta-variant tool, the description covers identity, current equivalence state, when to use it, and its evaluation role. The response shape is delegated to ask_pipeworx ('same response shape'), which is reasonable shorthand since the stable sibling documents the contract. Minor gaps: no mention of failure modes or latency characteristics of the 'experimental edge,' and no explicit statement of what the grounded sibling offers instead.

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%: all six parameters (required question plus five documented aliases q, text, input, query, prompt) are fully described in the schema. The description adds nothing about parameters, which is acceptable because the schema carries the full burden. 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 states a concrete function: a beta 'universal router' over 5,798 tools with identical arguments and response shape to ask_pipeworx. It clearly positions itself relative to siblings — the experimental edge of ask_pipeworx, distinct from the stable router and the grounded variant. An agent can tell exactly what this tool is and how it relates to its siblings without opening the schema.

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

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

Explicit usage guidance is given: 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router.' This states when to pick this tool and names the stable router as the alternative. It lacks an explicit when-not-to-use clause (e.g., prefer stable when consistency matters) and does not contrast with ask_pipeworx_grounded, so it stops short of a 5.

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

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

Beyond the annotations, the description discloses significant behavioral traits: it may explicitly refuse to answer, it returns verbatim evidence, it uses only the tool result, and it costs an additional LLM call. The refusal_reason enum is specified, giving the agent a precise mental model of failure modes. This far exceeds what the annotations alone convey.

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

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

The description is information-dense but well-organized: purpose and mechanism first, then the exact output contract, then when to use it and when not. Every sentence earns its place, and the cost trade-off is prominently included.

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

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

The description is sufficient for a complex grounded-answer tool. It defines success and refusal shapes, lists refusal reasons, explains the routing behavior, and gives usage boundaries. No output schema exists, so the description's detailed return contract is especially valuable and complete.

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

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

Schema description coverage is 100%, so the schema already fully documents the question parameter and its aliases. The tool description adds no additional parameter-level semantics, so it meets but does not exceed the baseline for high schema coverage.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, with a specific mechanism: it routes through the same pipeline as ask_pipeworx but extracts answers only from tool results. It also distinguishes itself from ask_pipeworx by emphasizing grounded answers, evidence, and refusals.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also provides a clear alternative condition, saying to 'prefer ask_pipeworx for casual lookups,' and even names the cost trade-off of one extra LLM call.

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

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

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?

The annotations already declare the tool read-only and idempotent, and the description adds substantial behavioral detail: parallel decomposition, gap[] reporting, ambiguity handling, contradictions[], hop fields, fetchable citation URIs, semantic excerpting, and expected latency. It also clearly discloses account requirements, so the safety and side-effect profile is fully transparent.

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 information-rich, with almost no filler, and it is front-loaded with the most critical gate (account requirement and alternative tool). However, it is quite long and contains minor redundancy, such as mentioning the paid plan for 'thorough' both at the start and in the depth explanation.

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

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

Given there is no output schema, the description thoroughly explains the return format: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], and hop fields. It also covers prerequisites, source scope, depth semantics, latency, and when to choose a sibling, making it complete for a complex tool.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema by explaining how 'depth' values behave (quick=3 facets, standard adds a gap-recovery hop, thorough adds a paid iterative pass) and how they affect latency. It also clarifies that 'question' is meant for natural-language multi-part questions and provides examples.

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 clear action: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' in one call, and explicitly distinguishes itself from open-web search. It also contrasts with siblings like ask_pipeworx for single lookups, so an agent can tell them apart.

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 direct routing guidance: use ask_pipeworx when not signed in and for single lookups, and use deep_research for broad/multi-part questions over structured data. It also notes the paid-plan constraint for 'thorough' depth, making when-to-use conditions explicit.

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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses fan-out sources, soft-fail behavior (e.g., USPTO PatentsView sunset, GDELT→GNews fallback), the semantics of empty sections (real no-data, not a bug), and name-resolution behavior. It also explains return fields like sources_used/sources_failed and the resolved_from/resolved_to fields, which significantly disambiguates expected 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 information-dense and front-loaded with example queries and a clear directive, but it is quite long and somewhat run-on, mixing several distinct concerns (input form, output fields, source list, failure semantics) into one paragraph. Every sentence earns its place, but the structure is harder to scan than 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?

Despite no output schema, the description is remarkably complete: it enumerates all major return categories, source-specific caveats, fallback chains, and an edge case (private company). An agent knows what to expect, how to interpret empty sections, and what inputs are valid. For a broad profile tool with no output schema, this is highly 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%, so the baseline is 3. The description adds meaningful context: it explains that `type` accepts 'company' or 'ticker' interchangeably with the same value shapes, which reinforces the schema's enum description, and it enumerates concrete example values and the private-company edge case. It doesn't go into every output detail but adds value beyond the schema.

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

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

The description opens with concrete user phrasings and states a specific verb+resource: full cross-source profile of a US public company in one parallel call. It clearly distinguishes itself from single-pack SEC/XBRL/news lookups and from siblings like deep_research or validate_claim by naming its output constituents.

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

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

Explicitly says ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view, and lists the exact accepted inputs (ticker, CIK, company name) with resolution behavior. It also handles an alternative case—private company returns resolved:false—which tells the agent when this tool is and isn't appropriate.

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 already declare readOnly, idempotent, and non-destructive behavior. The description adds genuine behavioral context beyond that: findings are included only 'when the FAC findings table carries them,' and the tool enriches the base audit record with federal program detail. It is transparent about conditional content and scope without contradicting the annotations.

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

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

The description is long but each clause adds relevant detail about the returned data; it is front-loaded with the primary purpose. The final sentence, 'Answers what did this specific audit cover and what did it conclude,' is somewhat redundant with the preceding enumeration, but overall the length is justified by 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?

With no output schema, the description carries the burden of explaining return values, and it does so thoroughly: summary_url, per-program CFDA numbers and expenditures, major program status, opinion type, auditee/auditor details, and conditional findings. It does not explicitly describe the result shape or error behavior, but for a read-only fetch tool the listed fields are sufficient guidance.

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 structured schema already documents all three parameters. The tool description reinforces report_id with a concrete example and clarifies the 'single audit' semantics, but it does not materially expand on award_limit or include_findings beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Fetch one single audit by its FAC report_id', and enumerates the key payload fields (summary_url, CFDA numbers, program names, expenditures, major program status, opinion type). This clearly distinguishes it from sibling tools like fac_search_audits (searching) and fac_audit_findings (findings-only), even though siblings are not named explicitly.

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 makes the use case clear: call this when you have a specific FAC report_id and need the full audit record with program-level and finding detail. It does not explicitly state when not to use it or name alternatives, but the 'one single audit by report_id' phrasing strongly implies the retrieval pattern and the schema's reference to fac_search_audits adds 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 (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?

The annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description then adds substantial behavioral detail beyond that: it reveals matching semantics ('matched as a forgiving case-insensitive substring'), bilingual name handling for Puerto Rico municipalities, and a graceful failure mode ('if it filters everything out the tool says which ZIPs FAC actually holds'). These insights are not in the annotations and help an agent predict tool behavior accurately.

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

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

The description is longer than average but deliberately structured: it opens with the core search capability, then audience coverage, then return fields, then special-case behavior, then the FAQ-style answers. Every sentence contributes distinct information, and the most important discriminator ('Search US single audits') is front-loaded. It could trim the exhaustive recipient-type list, but the list reinforces scope and is not filler.

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

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

There is no output schema, so the description's explicit enumeration of returned fields (report_id, summary_url, organization name, city/state/ZIP, total federal awards, cognizant agency, acceptance date) is essential and provided. The behavior around prefix ZIP matching, name substring matching, bilingual municipalities, and feedback when a filter excludes everything is also disclosed. With 12 parameters and no output schema, nothing an agent needs to call this correctly 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 description coverage is 100%, so every parameter already has a thoughtful description in the input schema, including aliases, matching semantics, and defaults. The description adds little beyond listing the searchable fields, which the schema already does. This meets the baseline of 3 because the schema carries the heavy lifting and the description doesn't conflict or add meaningful new parameter meaning.

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

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

The description begins with a specific verb+resource pair: 'Search US single audits ... filed with the Federal Audit Clearinghouse.' It then enumerates the search dimensions (name, UEI, EIN, state, ZIP, audit year, federal dollars) and the returned fields (report_id, summary_url, etc.), making the tool's role unmistakable. It also implicitly differentiates from sibling tools like fac_get_audit or fac_audit_findings by emphasizing multi-criteria search over retrieval of a single audit or findings.

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 by stating the exact questions it answers ('does this grant recipient file a single audit and how much federal money does it run') and the scope ('Covers every kind of non-federal recipient...'). However, it does not explicitly contrast with sibling tools such as fac_audit_findings, fac_federal_awards_by_program, or fac_get_audit, so an agent must infer when to choose this search over those alternatives. This is clear context without explicit exclusions or named 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 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?

The description goes far beyond the annotations, which already mark it as read-only, open-world, and idempotent. It discloses the token-overlap matching mechanism, safety fields, warning codes, the fact that returns are gross spreads without fee modeling, skipped leg categories, and the meaning of null temporal alignment. This is exceptionally transparent about behavior and limitations.

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

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

The description is long but appropriately so for a complex, behavior-heavy tool with no output schema. It is well organized with labeled sections (modes, response, safety fields, codes, skipped counters, fees). Some details are repeated across prose and flag lists, so it is not maximally concise, but it earns most of its length.

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

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

Because there is no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: leg-by-leg prices, top_spreads_pp, compatibility_warning, compatibility_codes, skipped counters, temporal_alignment semantics, and fee caveats. Nothing essential is missing for an agent to understand what the tool returns and what the fields mean.

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

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

The input schema already covers all 3 parameters at 100% coverage, so the baseline is a 3. The description adds value by explaining the interaction between modes, that explicit parameters override topic-mapped sides, and that both modes run the same matcher. It reinforces, but does not heavily expand beyond, what the schema already documents.

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, differentiated purpose: computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It clearly distinguishes itself from same-venue tools like polymarket_edges by emphasizing the cross-venue comparison and the same-question constraint. The mention of two modes and a matcher further clarifies what the tool actually computes.

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

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

The description gives strong practical guidance on when to use the tool: it explains the topic shortcuts, the explicit pairing mode, and the caveat that pre-mapped topics are not necessarily tradeable. However, it does not explicitly name sibling alternatives or state when NOT to use this tool versus same-venue arbitrage/edge tools, so the guidance is contextual rather than comparative.

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?

Despite annotations already marking the tool read-only/idempotent/non-destructive, the description adds substantial behavior: it cascades through multiple lookup endpoints, degrades gracefully if GLEIF/OpenFIGI are down, returns ownership chains when LEI resolves, and resolves non-equity instruments that lack tickers. This goes far 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 front-loads with user-phrase examples and is information-dense, but it is a long run-on paragraph with a duplicated sentence ('Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups' appears twice). Structure could be improved with bullets per entity type.

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 covers return contents for both types (CIK, ticker, company_name, LEI, parent/ultimate-parent/children, FIGI, RxCUI, ingredient, brand, citation) and explains fallback behavior. It does not explicitly state the response format for unresolvable names or rate limits, but these are minor given the completeness elsewhere.

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

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

The schema already provides 100% parameter coverage with examples in the value description. The main description reinforces type-specific behavior (e.g., exact ticker map vs name search for company, brand/generic name for drug), adding meaning beyond the schema's structural 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 uses a clear verb phrase — 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input' — and backs it with a list of example questions. It distinguishes itself from siblings by naming compare_entities for pairwise name matching, making the tool's scope unambiguous.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID' and gives example query patterns for when it applies. It also tells agents when not to use it ('use compare_entities for pairwise name matching'), though it does not enumerate all sibling alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. 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.