Us Gov Contracts

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

Annotations already declare this as read-only, open-world, idempotent, and non-destructive. The description adds useful behavioral context: the default free model (Workers AI), the BYO key requirement for Anthropic with direct payment to Anthropic, and the return shape. 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?

Three sentences, front-loaded with the core action, and every sentence earns its place: function, model/cost detail, and use cases. No fluff 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 tool with 4 parameters, no output schema, and strong annotations, the description provides everything needed: purpose, model selection, cost implication, and the return structure (per-model plus combined view). It is fully contextualized.

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 goes beyond by explaining the default model and the role of `_apiKey` (to also probe Anthropic), adding semantic clarity to the parameters.

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

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

The description opens with a specific verb 'Probe' and clearly identifies the resource (LLMs) and the output (visibility score 0-100 per model). It distinguishes itself from sibling tools like ask_pipeworx or scan_competitor_ai_presence by focusing on multi-model AI visibility scoring.

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

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

It states clear use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' However, it does not explicitly mention alternatives or situations where this tool should not be used, stopping short of full exclusion criteria.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive hints. The description adds valuable behavioral context: it routes to 5,462 tools, fills arguments automatically, returns structured answers with stable citation URIs, works on every tier, and is a single fast call. This goes beyond annotations, though it doesn't detail failure modes or rate limits—acceptable given the annotation coverage.

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

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

The description is longer than average, but every section earns its place: domain list, routing behavior, trigger phrases, examples, and explicit alternative guidance. It is front-loaded with the most critical instruction ('PREFER OVER WEB SEARCH') and remains well-structured. Slight redundancy in the examples could be trimmed, but overall efficient for the information conveyed.

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

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

Given the tool's complexity (no output schema, many aliases, multiple siblings), the description is remarkably complete. It covers what the tool does, when to use it (including trigger phrases), how it behaves (routes, fills arguments, returns citations), when to escalate to alternatives, and provides varied examples. No gaps remain for the agent to infer critical usage 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 description does not explain parameters, but the schema covers 100% of parameters with clear descriptions and multiple aliases. The examples in the schema and description illustrate usage. Since schema_coverage is 100%, a baseline 3 is appropriate; the description adds no extra semantic value beyond what the schema already provides.

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

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

The description clearly states the tool's purpose: answering factual questions by routing to verified sources and returning structured answers with citations. It uses a specific verb ('prefer over web search for questions about...') and explicitly distinguishes from siblings like ask_pipeworx_grounded and deep_research, so no ambiguity remains.

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?

Usage guidance is exceptionally explicit: it says 'PREFER OVER WEB SEARCH' for a broad list of domains, 'START HERE' as the default entry point, and provides step-up alternatives ('Step up only when needed') with specific conditions. This directly tells the agent when to use this tool vs alternatives.

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

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

Beyond the readOnly/idempotent annotations, the description discloses that routing improvements are enabled live during tests, that results are compared against the stable router, and that there is no fallback—it is a full working router. This adds significant behavioral insight.

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

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

Four sentences, each adding value: purpose, current status, usage guidance, and a clarifying note that it is fully functional. No redundancy or filler.

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

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

The description explains the tool's scope (5,462 tools), its experimental nature, and that the response shape is identical to ask_pipeworx. While no output schema exists, the reference to ask_pipeworx provides enough context for an agent to infer behavior. A minor gap is not detailing response contents directly.

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

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

The schema has 100% coverage with descriptive parameter text, so the description doesn't need to repeat parameter details. It merely refers to 'same arguments' as ask_pipeworx, which is sufficient given the schema's completeness.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with 5,462 tools, and distinguishes it from stable alternatives by emphasizing it is an experimental edge. It explicitly mentions identical arguments and response shape, so purpose is unambiguous.

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

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

Explicit guidance is provided: "Use it exactly like ask_pipeworx when you want the newest routing." It also notes that with no active candidate it currently matches ask_pipeworx exactly, giving clear when-to-use context and implying the stable alternative.

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

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

Discloses that it is hallucination-resistant, returns structured refusal reasons, costs an extra LLM call, and details the exact refusal reasons. Annotations already declare readOnly/openWorld/idempotent, so the description adds contextual behavior beyond that. It also explains the trade-off vs the non-grounded sibling.

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

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

The description is dense but well-structured, front-loading the core differentiator ('Hallucination-resistant') before explaining mechanism, behavior, use cases, and cost. Each sentence contributes unique information; while longer than the TDQS 4.3 example, the added complexity of the tool justifies most of it. A slight trim could improve conciseness.

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

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

Despite no output schema, the description fully specifies the return object fields and failure refusal reasons, plus real-world use cases. It also mentions the extra LLM call and when to prefer the cheaper sibling. Combined with annotations, this is complete 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 coverage is 100% with all six parameters being aliases for the same required 'question' field, so the schema already fully documents parameter semantics. The description adds no additional parameter information, which is acceptable given the aliases are trivial. Baseline 3 applies.

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

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

The description clearly identifies this as 'Hallucination-resistant answer mode for high-stakes reads' and contrasts it with ask_pipeworx by noting it extracts answers 'using ONLY what the tool result contains.' This specific verb+resource+distinguishing trait sets it apart from sibling tools like ask_pipeworx and bet_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?

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also provides an exclusion: 'prefer ask_pipeworx for casual lookups.' This is a textbook case of when/when-not guidance.

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

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

Despite annotations already marking readOnly/openWorld/idempotent/non-destructive, the description adds extensive behavioral detail: resolver match confidence, parent-event extraction, news fallback flags, low-confidence short-circuiting, closed-market handling, wide-spread market flags, and cancellation-rule risk. No contradiction with annotations.

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

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

The description is long but well-structured with CAPS-labeled sections and front-loaded with the core purpose. Every section earns its place by covering distinct aspects (resolver, safety, cancellation rules), though a few minor redundancies exist (e.g., the explanation of blocking routes).

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?

Since there is no output schema, the description carries the full burden of explaining return values. It thoroughly documents response shapes (market, analysis, evidence), resolver contract, parent_event, news fields, and safety statuses, giving an agent actionable expectations for interpreting 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?

Schema description coverage is 100%, so the baseline is 3. The description adds examples of market inputs (slug, URL, question) but largely restates what the schema already provides. It does not add deeper meaning for depth or include_raw beyond the schema's own 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 first sentence uses a specific verb ('Research') and resource ('a Polymarket bet by pulling relevant Pipeworx data'), making the tool's purpose unmistakable. It also differentiates from sibling tools by focusing on bet-specific research and provides concrete use-case phrases ('should I bet on X', 'what does the data say about Y').

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 with query examples and gives rich fan-out examples by market category. However, it does not name alternative sibling tools or state when NOT to use it, so it falls short of a 5.

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

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

Annotations already mark this as read-only and idempotent, but the description adds rich behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), off-calendar fiscal year handling, sorting by primary metric, and output as paired data with citation URIs. This goes well 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 long but every sentence earns its place. It is front-loaded with examples, then states preference, then type-specific data details, sorting, and output format. No unnecessary repetition or filler.

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

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

Despite having no output schema, the description fully explains the return format (paired data + pipeworx:// citation URIs), sorting behavior, and data sources. Combined with the annotations, the agent has all necessary information 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 coverage is 100%, but the description adds substantial meaning: it explains that 'values' for company should be tickers/CIKs, for drug should be names, and gives concrete examples. It also clarifies what metrics each type retrieves, which directly informs how to set both parameters.

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

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

The description clearly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' and provides multiple example queries. It distinguishes from siblings like entity_profile by emphasizing multi-entity comparison and the 'ALWAYS PREFER' guidance.

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

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

It explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' giving clear when-to-use guidance. It also details what each type (company vs drug) retrieves, helping the agent choose the right parameters for the task.

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 substantial context beyond annotations: account requirement and auth URL, depth-dependent latency (15–60s, up to ~90s), parallel decomposition, gap[] and contradictions[] behavior, citation_uri only when resolvable, semantic excerpting of large records. All behaviors are consistent with readOnlyHint, openWorldHint, and idempotentHint; no contradiction.

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

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

The description is long but front-loaded with the account prerequisite and core purpose, then organized into alternatives, depth behavior, citation guarantees, and latency expectations. Each sentence carries unique information; bolded terms and code formatting aid scanning. No fluff or filler.

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

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

Even without an output schema, the description fully specifies the return format: findings packet with verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citation, gaps[], contradictions[], and hop field. It also covers auth, latency, tool selection, and edge cases (current news returns empty gaps), making it complete for a complex research 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% and already defines both parameters richly, so baseline is 3. The description adds extra value: depth 'thorough' requires a paid plan, 'standard' is the default and re-angles unanswered gaps, and concrete example questions are given. This goes beyond what the schema alone provides, though some depth details are redundant with 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, multi-part behavior: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources... Decomposes your question into focused facets, routes each to the right one of 5,462 tools IN PARALLEL, and returns a findings packet.' It clearly distinguishes itself from ask_pipeworx and open-web search, and the title 'Deep Research' matches the described functionality.

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

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

Provides explicit when-to-use and when-not-to guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead — it works on every tier.' This is textbook-level usage 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details about the return format (names, descriptions, full input schemas, curated examples) and that results are directly callable without a second schema lookup. This goes beyond the annotations without contradicting them.

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

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

The description is structured across three sentences: purpose, scope examples, and return/usage. The domain list is long but directly informs the user what queries work. Every sentence contributes value; no filler. It is not as tight as a two-sentence ideal but remains efficient and well-organized.

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 clearly explains the return value (tool names, descriptions, full input schemas, curated examples) and that results are callable directly. With 6 parameters (many aliases) and many sibling tools, the description fully covers what a user needs to know to invoke the tool and interpret its output.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances parameter understanding by listing concrete example queries (e.g., 'analyze housing market trends', 'look up FDA drug approvals') and enumerating the domains (SEC filings, drugs, real estate, etc.) expected in the query. This adds meaning beyond the schema's generic 'Natural language description'.

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

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

The description opens with a specific verb and resource: "Find tools by describing the data or task." It clearly distinguishes this tool from siblings by explaining it returns top-N relevant tools with full schemas, which is unique among the listed tools. The purpose is unambiguous.

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

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

The description provides explicit usage context: "Use when you need to browse, search, look up, or discover what tools exist" and "Call this FIRST when you have many tools available and want to see the option set." It stops short of naming specific alternatives or when-not-to-use scenarios, but the guidance is strong and actionable.

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/idempotent annotations, the description discloses realistic behavioral details: parallel fan-out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), exact return fields with constraints (up to 5 filings, latest 10-K fundamentals), and a known degradation path ('USPTO PatentsView API sunset May 2025 — soft-fails until reactivated'). It also reveals the GDELT→GNews fallback chain, giving the agent an accurate model of what will happen.

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; the opening query examples immediately convey the tool's purpose, and the output list is structured with semicolons and parentheticals. No filler sentences are present, though the length could be slightly trimmed without losing value.

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

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

With no output schema, the description must bear the burden of explaining return values, and it does so thoroughly: it enumerates all returned groups (cik/company_name, filings, fundamentals, patents, news, LEI) with key details like URIs and sort order. It also covers input format and failure modes, making the tool self-contained for an 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 schema already fully describes both parameters (type enum and value as ticker/CIK), so this dimension is mainly about added clarity. The description adds concrete examples ('AAPL', '0000320193'), the zero-padding nuance for CIKs, and reiterates the name-not-supported constraint with a pointer to resolve_entity. These practical examples go beyond the schema's terse description.

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

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

The description clearly identifies the tool as creating a 'full cross-source profile of a US public company in ONE parallel call' and enumerates the exact data sources and output fields. This distinguishes it from sibling tools like resolve_entity (name resolution only) and single-purpose lookups by explicitly positioning it as the holistic alternative.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', giving a clear when-to-use rule. It also provides a strong when-not-to-use warning: 'names not supported (use resolve_entity first if you only have a name)', naming the alternative tool. The example queries further anchor the intended invocation 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 destructiveHint=true and idempotentHint=true. The description adds context that this clears sensitive agent-saved data and is for stale/done contexts. While it doesn't detail edge cases like missing keys, annotations cover the core behavioral profile.

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

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

Two sentences, front-loaded with the action, followed by clear usage guidance and sibling pairing. 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?

With one parameter, no output schema, and annotations present, the description covers purpose, usage, and context. It lacks details about return behavior, but given the tool's simplicity, this is not a significant gap.

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 the only parameter fully with its own description. The description adds the context of 'saved earlier' but doesn't add new parameter semantics 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 the specific verb 'Delete' with the resource 'previously stored memory' and identifies 'by key', clearly distinguishing it from siblings like remember and recall.

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

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

It explicitly lists when to use: stale context, task done, or clearing sensitive data. It acknowledges related tools ('Pair with remember and recall') but does not explicitly state when NOT to use it, so slightly below a 5.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds value by disclosing the process (fetches the page, extracts title/description/key links) and the output format (single text blob ready for site-root), which is not covered by annotations. It does not discuss edge cases like errors or redirects, but given the strong annotation base, it builds trust adequately.

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

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

The description is three sentences long, front-loaded with the primary action and outcome. Each sentence earns its place: the first states purpose and audience, the second explains the mechanism, and the third lists concrete use cases. There is no redundancy or filler.

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

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

For a tool with only two parameters and no output schema, the description thoroughly covers what it does, how it works, what the output looks like, and when it is useful. It also aligns with the annotations (read-only, idempotent) without contradicting them. No critical contextual gap remains.

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% description coverage for both parameters (url and max_links), so the schema already documents them clearly. The description does not add additional parameter-level meaning beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, with the specific goal of helping AI crawlers index the site. It names the exact action ('generate') and resource ('llms.txt'), and distinguishes itself from sibling tools (which are mostly research/search tools) by focusing on file generation for AI crawlers.

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 use cases ('Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving the agent context on when to apply the tool. It does not explicitly mention when not to use it or point to alternatives, but the context is sufficient.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond that: the output includes each jurisdiction's key, level, data platform, source dataset URL, and live record count, and the split by type. This gives the agent a clear picture of what to expect without contradicting any annotations.

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

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

The description is a single, well-structured sentence that starts with the action verb 'List'. It packs in all essential details—scope, split, and specific output fields—without any unnecessary words. Every clause earns its place.

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

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

Given the tool's simplicity (no parameters, no output schema), the description is remarkably complete. It specifies exactly what the returned list will contain and its relationship to sibling search tools. There is no glaring omission such as pagination or filtering, since none apply.

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 tool has zero parameters, and the input schema shows an empty object. Per the rubric, a no-parameter tool gets a baseline of 4. The description adds no parameter details, but none are needed; the schema fully covers this aspect.

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 the verb 'List' and specifies the resource ('US state & local jurisdictions covered by this pack'), making the tool's purpose immediately clear. It also distinguishes itself from sibling tools by explicitly mentioning the split into contract-award and spending/checkbook jurisdictions, tying them to gov_contracts_search and gov_spending_search.

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

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

The description provides clear context by referencing the two sibling search tools and explaining that this tool lists jurisdictions covered by each. While it does not explicitly say 'use this when you need an overview, use search tools for actual searches', the implication is strong enough to guide an agent. Lacks an explicit 'when not to use' statement, so not 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?

The annotation set (readOnly, openWorld, idempotent, non-destructive) already establishes safety; the description adds context: 'keyless open data' (no auth), 'normalized across jurisdictions', coverage of state/county registries, and the return fields. This is rich behavioral context beyond annotations.

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

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

Four sentences deliver all essential information: purpose, filters, jurisdiction handling, return fields, and federal-tool exclusion. No filler or redundancy; front-loaded with the primary action.

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

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

Given 6 optional params, no output schema, and rich annotations, the description covers the return structure, filtering semantics, scope, and alternative tools. The only non-schema detail is the jurisdiction key pointer, which is present. It's complete for an agent to use this tool correctly.

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

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

Schema coverage is 100% with detailed property descriptions. The description restates the filterable fields but adds value by linking the `jurisdiction` parameter to gov_contracts_jurisdictions, telling the agent where to obtain valid keys. That cross-reference earns above-baseline credit.

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-resource pair ('Search AWARDED US state & local government contracts'), and later specifies 'This is STATE/LOCAL award data' to distinguish from federal contract tools. It also enumerates filter types, making the purpose unmistakable.

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

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

It explicitly states when not to use it ('for federal contracts use USAspending/SAM tools') and describes how to scope by jurisdiction (omit for all, pass key for specific), referencing gov_contracts_jurisdictions for key lookup. This is clear when-to-use guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds value by clarifying that results are actual expenditures (not award values), stating the return fields (vendor, agency, amount, category, fiscal year), and noting 'Keyless' access. It does not repeat or contradict annotations, but it doesn't go beyond what annotations cover in terms of operational edge cases (e.g., pagination or rate limits), hence a 4 rather than 5.

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

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

The description is a single dense paragraph of about 70 words. Every sentence earns its place: the opening defines the core purpose; the second clarifies the distinction from contracts; the third lists filters; the fourth explains jurisdiction; the fifth lists returns; the sixth names the alternative. No fluff, no repetition.

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

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

With no output schema and six parameters, the description compensates by covering the tool's purpose, scope, filtering options, jurisdiction behavior, return fields, and the relationship to sibling tools. The annotations handle the safety profile (read-only, idempotent, non-destructive), so nothing critical is missing for a search/list tool.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description adds contextual meaning by explaining that 'keyword' matches the spending category/description, that 'min_amount' filters by dollars of actual payments, and that 'jurisdiction' is optional and omittable for a nationwide search. It also clarifies that 'agency' refers to the paying agency, which aligns with the schema's 'Paying agency/department.'

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 pair ('Search US STATE government spending / vendor payments') and immediately distinguishes from the sibling tool gov_contracts_search by contrasting 'awarded contracts' with 'actual payments.' The scope (state-level checkbook data), filterable dimensions, and return fields are all clearly stated.

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 names the alternative for awarded contracts ('Use gov_contracts_search for awarded contracts; use this for actual payments/expenditures'), tells when to pass a jurisdiction key (or omit it for all states), references gov_contracts_jurisdictions for valid keys, and notes 'Keyless' (no auth needed). This leaves no ambiguity about when to use this tool.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description doesn't need to repeat those. It adds value by disclosing that it returns only active subscriptions by default and lists the exact fields returned, going beyond the structured annotations. It does not contradict any 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?

The description is two sentences: the first states the core purpose and return fields, the second gives usage guidance. Every word earns its place, and the key information is front-loaded. No superfluous content.

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

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

For a simple list tool with no required parameters and no output schema, the description is complete. It covers what the tool returns, the default behavior regarding active subscriptions, and practical use cases. There are no gaps given the tool's low complexity.

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

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

Schema coverage is 100% for the single parameter (include_inactive), so the schema already explains the parameter fully. The description reinforces that the default is active-only subscriptions, but it doesn't add much beyond the schema's own description. Baseline 3 is appropriate given the schema does the heavy lifting.

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 with a specific verb ('List') and resource ('the caller's active subscriptions'), and it distinguishes itself from sibling tools by specifying the returned fields (id, type, params, etc.). It also implies the relationship to subscribe/unsubscribe, making its role unambiguous.

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

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

The description explicitly tells users when to use this tool: to review current monitoring before adding more subscriptions or to find an id to cancel. This provides clear context and indirectly contrasts it with the subscribe and unsubscribe sibling tools, offering concrete use cases.

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

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

Annotations are all false and don't disclose safety or effects. The description compensates by adding important behavioral context: rate-limited to 5 per identifier per day, free and not counting against tool-call quota, and that the team reads digests daily affecting roadmap. It also includes a content constraint (don't paste end-user prompts). This goes beyond annotations, though it doesn't describe the submission outcome or side effects. 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 detailed but every sentence earns its place: purpose, use cases, exclusion, message guidance, rate limit, and quota context. It is front-loaded with the main purpose. Though longer than the calibration 'ideal' of two sentences, the extra length is necessary for a feedback tool with nuanced usage rules; no filler.

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

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

With 3 parameters (2 required), a nested context object, and no output schema, the description fully equips the agent: it explains the tool's purpose, when to use, when not to use (other MCP servers), how to format a good message, rate limits, and quota impact. There are no missing pieces for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra parameter-specific guidance beyond the schema: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt' and message guidance ('Be specific... 1-2 sentences typical, 2000 chars max'). This enhances understanding of how to fill the message and context fields, earning a 4.

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

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

The description clearly states the tool's function: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It also enumerates the feedback types (bug, feature/data_gap, praise), which distinguishes it from all sibling tools that are research or subscription related. No other sibling serves as a feedback channel.

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

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

Provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' This fully covers when and when not to use, with 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 cover safety (readOnlyHint, idempotentHint, destructiveHint false), and the description adds valuable behavioral context: data is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. This goes beyond the annotations without contradiction.

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

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

The description is well-structured: an opening summary, a bulleted 'Useful for' list, and a final sentence about data sourcing and caching. It's slightly longer than minimal but every sentence earns its place, and the front-loaded first sentence immediately communicates the tool's 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?

For a simple read-only tool with one optional parameter and no output schema, the description is complete: it explains what is returned (top tools, top packs, total call volume), the data source, caching behavior, and privacy (no PII). No critical context is missing for an agent to decide whether to invoke this tool.

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

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

Schema description coverage is 100% because the 'window' parameter includes a detailed description of its enum values and semantics ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The description's mention of '24h, 7d, or 30d' simply repeats this, adding no extra meaning beyond the schema.

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

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

The description clearly states what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window' based on what other AI agents are calling. This specific verb+resource combination distinguishes it from siblings like discover_tools or ask_pipeworx, which focus on different functions.

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 three explicit 'Useful for' scenarios: discovering hot data sources, confirming canonical tool choices, and checking alignment of use cases. This is clear context for when to use the tool, though it does not explicitly mention alternatives or exclusion cases, so it doesn't reach a 5.

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

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

Annotations declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial context: how scans work, partition filters, placeholders, similarity thresholds, fill-check logic, and the warning that realizable_edge_pp ≤ 0 means the opportunity is not tradeable. This goes far beyond annotations, providing actionable behavioral nuances.

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

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

The description is long but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. Every sentence carries specific information, and the length is justified by the tool's complexity. 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?

With no output schema, the description must explain return values, and it does thoroughly: response structure (opportunities[], partition_check{...}), null signal conditions, fill-check behavior, and when to refer to polymarket_fill_risk. It covers all operational contingencies, making it complete for an API with two optional parameters and no formal output schema.

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

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

Schema coverage is 100% with both parameters well-described. The description adds extra semantics: examples of slugs and seed questions, full URL acceptance, mode-specific behavior (walks child markets, checks date/threshold ordering), and the recommended use case per parameter. This enriches the schema but is not dramatically more than the schema already provides.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from siblings like polymarket_edges (edge tracking) and polymarket_fill_risk (fill pricing) by focusing on arbitrage detection. The three modes (trending_scan, event, topic) further clarify its scope.

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

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

The description gives explicit when-to-use instructions: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also explains when to use fill_check and recommends polymarket_fill_risk for custom sizing, clearly differentiating from alternatives.

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

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

Annotations declare read-only/idempotent, and the description adds extensive behavioral context: caching at the KV level keyed on all knobs, edge net of slippage, Kelly capping, 24h-move warnings, and diagnostic fields to explain empty segments. It also explains the reasoning behind excluding Fed candidates. 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?

Front-loaded with a clear purpose sentence. Uses structured section labels (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and detailed thresholds that are dense but relevant. Longer than average, but every sentence provides substantive detail.

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

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

Without an output schema, the description covers the full response structure, opportunity fields, and knob effects. It even explains why Fed candidates are unranked and what diagnostics are included. This is fully sufficient for an agent to invoke and 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?

Schema descriptions cover all 9 parameters, so baseline is 3. The description adds value by explaining how min_partition_leg_kelly interacts with partition arbs (parent Kelly is 0) and by grouping tradeable-edge knobs. There's some redundancy, but it enhances 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?

Clearly states it scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. The description includes the intended use case ('what should I bet on today') and details the three segments, distinguishing it from sibling tools that focus on arbitrage or 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?

States the tool is built for opportunity discovery without paging hundreds of markets. It describes when to use it (daily betting research) but doesn't explicitly contrast with sibling tools like polymarket_arbitrage or bet_research. However, the unique model families and filtering knobs imply when it's 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?

Despite strong annotations (readOnlyHint=true, destructiveHint=false), the description adds substantial behavioral detail: snapshot TTL, cache-miss write behavior, data gaps meaning no scan, computation from daily closes net of slippage, and inclusion of expired opportunities. 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 perfectly structured with labels (Args, RESPONSE, LIMITS). Every sentence carries essential information—no filler. The front-loaded purpose sentence immediately orients the agent, and the labeled sections enable quick parsing.

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

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

For a complex telemetry tool with no output schema, the description fully explains the response structure (tracked[], expired[], snapshot_dates[]), field semantics, computation methodology, and data limitations. Nothing critical is left implicit.

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 enhances parameter meaning by explaining 'window' as 'snapshot family' and explicitly listing valid options (24hr | 1wk | 1mo) and days clamping, plus how both affect the response timeline. This goes beyond the schema's basic 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 opens with a specific verb-resource pair: '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 differentiates from sibling tools by focusing on time-series edge behavior rather than current edges or arbitrage.

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

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

The description implies usage through the core question and contrast between fresh vs old edges, and mentions the median lifespan as a 'competition clock.' It does not explicitly name alternative tools or state when not to use, but the positioning relative to polymarket_edges is clear. The LIMITS section also provides implicit exclusions (e.g., not for intraday).

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?

It discloses behavioral details beyond the annotations: 'walks the ladder', returns a verdict (clean|degraded|cannot_fill), and warns about partial basket fills turning arbs into unhedged directional positions. This is execution-level insight not covered by readOnlyHint or idempotentHint.

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

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

The description is dense but well-structured: bold section headers for SINGLE-MARKET and BASKET, and all-caps emphasis for critical directives like 'REQUIRES' and 'USE THIS' aid scannability. Every sentence adds essential operational context without repetition.

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

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

Given the tool's complexity and lack of an output schema, the description thoroughly enumerates return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, capture_ratio, thin_legs, etc.), explains clamping behavior, and covers edge cases like partial fills. It leaves almost no behavioral ambiguity.

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

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

Even though the input schema has 100% description coverage, the tool description enriches parameter meaning with mode-specific semantics: 'size_usd ... max spend on buys, target proceeds on sells' for single-market vs 'settlement notional S (shares per leg)' for basket. It also explains side defaults and the market/event one-of requirement.

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

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

The description opens with a clear verb-resource statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by explicitly positioning itself as the pre-trade real-world feasibility 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 tells 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 names the failure mode this tool guards against, making the alternatives clear.

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

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

The description extensively discloses behavior beyond annotations: it explains compatibility_warning triggers, temporal_alignment, skipped_cross_type/subtype counters, and the meaning of matched_pairs:0 cases. It even clarifies when spreads are not meaningful. This is rich behavioral detail far exceeding the basic read-only 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?

The description is fairly long but well-organized into labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence provides meaningful detail for a complex tool. It is front-loaded with the core purpose. Slightly long, but justified given the absence of an output schema and the need to explain edge cases.

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

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

With no output schema, the description must explain return values, and it does thoroughly: leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. It also covers parameter relationships and edge cases, making it complete for an agent to 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?

Schema descriptions already cover each parameter, but the description adds semantic relationships: how topic shortcuts map to the two explicit parameters, that explicit fields override the topic-mapped side, and the exact list of shortcuts. This adds context beyond the schema's field 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's function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the resource (two prediction markets) and the operation (calculating spread), and distinguishes it from siblings like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description explains two usage modes (topic shortcuts vs explicit ticker/slug) and gives context when each is appropriate. It warns that 'pre-mapped ≠ tradeable' and that most topics return compatibility_warning, providing implicit caution. However, it does not explicitly name alternative sibling tools, so a deduction for lacking direct comparison.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful beyond-annotation context: the scoping mechanism (anonymous IP, BYO key hash, account ID) and the behavior when key is omitted (list all keys). 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?

Three sentences, each earning its place: the operation, the use case, and the scoping/companion tools. No fluff, fully front-loaded with the core action, and structured to be quickly parsed.

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 single-parameter tool with no output schema, the description covers all key aspects: what it does, when to use it, how it scopes, and how it relates to siblings. It leaves no meaningful gaps for an agent to select and invoke it correctly.

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

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

Schema coverage is 100% and the schema already describes the key parameter and the omit-to-list behavior. The description reinforces this by explicitly stating 'omit the key argument' and explains the stored-value semantics (previously saved via remember), adding practical meaning without duplicating 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 uses a specific verb ('retrieve') and resource ('a value previously saved via remember'), and clearly distinguishes the two modes (retrieve by key or list all keys). It also differentiates from siblings by naming remember and forget 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?

Provides explicit context: use it to look up previously stored context (ticker, address, notes) to avoid re-deriving. Names complementary tools (remember to save, forget to delete) and clarifies scoping by identifier, giving clear when-to-use versus alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds crucial behavior beyond that: it discloses that setting mark_read:true changes feed state ('flag returned events read so the next call only shows newer ones'), which is a side effect not obvious from the annotations. It also reveals the return structure (source, citation_uri, raw event payload) and the existence of an external URL for the same feed. No contradiction with annotations; this is exemplary transparency.

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

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

The description is compact—three sentences—and front-loads the core action ('Pull fired events from your subscription feed'). Each subsequent sentence adds distinct value: return payload, filtering, mark_read semantics, and an alternative access point. There is no redundant filler or repetition of schema details, making it highly efficient.

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

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

Given the lack of an output schema, the description compensates by describing what each alert carries (source, citation_uri, raw event payload). It also explains the feed's persistence and provides a URL for external use, which helps the agent understand the broader context. However, it does not mention the default ordering (implied by 'most recent' but not explicit) or the behavior of unread_only, though these are in the schema. For a read-only tool with five optional parameters, this is reasonably complete, but a small gap remains.

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, but the description adds meaningful context. It gives a concrete example for type ('sec_8k') and clarifies the since parameter as an ISO timestamp. It also expands on mark_read's behavior beyond the schema's one-liner, explaining the effect on future calls. It does not mention unread_only or limit, but the schema already covers those, and the description's additional guidance for key parameters earns a 4.

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

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

The description opens with 'Pull fired events from your subscription feed,' which is a specific verb-resource pairing that clearly distinguishes this tool from sibling tools like list_subscriptions (lists subscriptions) and recent_changes (changes to something else). It further clarifies the resource by noting these are alerts written by 'the evaluator' to a 'persisted feed,' leaving no ambiguity about the tool's function.

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 usage context by explaining filtering options ('Filter by type... and/or since') and explicitly states 'Polls work fine,' which implies the tool is suitable for repeated checks. It also offers an alternative access method ('same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards'), which signals when one might prefer the URL over the tool. However, it does not explicitly contrast with sibling read tools or state when not to use it, so it misses a full exclusionary guideline.

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, idempotentHint, openWorldHint), the description discloses important behavioral details: fan-out to three distinct data sources, the GDELT-to-GNews fallback path, and the PatentsView API sunset causing a soft-fail. It also states the exact return shape (changes[] grouped by source, total_changes count, pipeworx:// citation URIs), which goes far beyond what annotations indicate.

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

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

Although the description is longer than typical, every clause adds value: query examples, source breakdown, fallback behavior, parameter semantics, output structure, and an explicit alternative. It is front-loaded with the purpose, then proceeds logically. No filler or redundant statements are present.

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 multi-source aggregation tool with no output schema, the description is remarkably complete. It covers parameters, source-specific behavior, fallback logic, soft-failure modes, return structure, and includes a pointer to an alternative tool. The agent has enough context to invoke it correctly and interpret results without resorting to other documentation.

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

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

The input schema already has 100% coverage with thorough descriptions for all three parameters (type enum, since format with examples, value as ticker/CIK). The tool description repeats the since format and adds a phrase about relative shorthand, but it doesn't materially extend beyond the schema. Baseline 3 is appropriate because the structured schema carries the burden.

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

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

The description clearly identifies the tool as a change feed for a company over a recent window, with specific query examples like 'What's new with X' and 'what happened to Z this week/month/quarter'. It differentiates from the sibling tool entity_profile by explicitly stating what entity_profile is for instead, and it lists the data sources (SEC, GDELT/GNews, USPTO) that make the purpose concrete.

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 usage guidance: it explains when to use this tool (for time-bounded recent changes/news/filings/patents) and explicitly says to use entity_profile instead for a static profile regardless of window. It also describes fallback behavior (GDELT→GNews on rate limits/5xx) and a sunset condition for an API, helping the agent set expectations.

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 (idempotent=true, destructive=false), the description adds meaningful behavioral context: key-value storage scoped by identifier, persistence differences for authenticated vs anonymous sessions (persistent vs 24-hour retention). This goes beyond what annotations provide without contradicting them.

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

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

Three tightly written sentences, front-loaded with the primary action, followed by use cases and technical details. Every sentence earns its place; no fluff or repetition. Ideal length for the tool's simplicity.

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 two-parameter tool with no output schema, the description covers all necessary context: what to save, when to save, storage scoping, retention policy, and paired retrieval/deletion tools. The agent has enough information to invoke correctly and orient itself within the tool family.

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%, thoroughly documenting both key and value properties. The description adds some semantic flavor ('a resolved ticker, a target address...') but does not materially enhance understanding beyond the schema's examples. Baseline 3 is appropriate since the schema carries the full burden.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' with a specific verb and resource. It distinguishes itself from siblings by explicitly naming companion tools recall and forget, making it obvious this is the write/save operation in a memory system.

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 usage guidance: 'Use when you discover something worth carrying forward...' with concrete examples (ticker, address, preference, research subject). Also names when to use the alternatives: 'Pair with recall to retrieve later, forget to delete.' This satisfies both 'when' and 'alternatives' criteria.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it cascades through several lookup endpoints, auto-disambiguates input, and returns citation URIs. It also specifies the exact return fields for each type despite no output schema.

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

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

The description is moderately long but well-structured with intent examples, usage guidance, and supported types. Every sentence contributes, though the cascading note at the end could be integrated more tightly. Overall it's efficient and readable.

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 two-parameter lookup tool with no output schema, the description compensates by listing return fields, citation URI patterns, and internal lookup behavior. It doesn't cover error cases or what happens if no match is found, but for this simple tool it's sufficiently 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 parameters are already well-documented. The description adds nuance by noting auto-disambiguation for company inputs and detailing the exact output fields linked to each input type. This provides a semantic layer 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 resolves user-spoken names to canonical/official identifiers, with concrete examples (ticker, CIK, RxCUI). It distinguishes itself from sibling tools by explicitly saying 'Use FIRST whenever you have a name but need an ID', which is a specific verb+resource+scope.

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

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

It gives an explicit rule for when to use: 'Use FIRST whenever you have a name but need an ID.' It also mentions that it replaces 2-3 manual lookups, providing context on efficiency. While it doesn't name an alternative tool, the usage condition is extremely clear.

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

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

The description discloses that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This adds behavioral context beyond the annotations (readOnlyHint, idempotentHint) by explaining the mechanics and output, though it does not detail potential rate limits or side effects (which are minimal given read-only nature).

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

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

The description is three sentences, front-loaded with the primary action, then mechanics, use case, and output. 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?

Despite having no output schema, the description explicitly states the return format ('ranked list with score, confidence, signal density per entity') and the use case. It also covers the multi-entity nature and ranking behavior, making it sufficient for an agent to select and invoke the tool appropriately.

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

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

Schema coverage is 100% with each parameter described. The description adds 'your brand + N competitors' and 'first entry treated as subject' but this is already reflected in the schema's entity description. The description does not provide additional parameter-level 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 'Compare' and states the resource: 'AI visibility across multiple entities side-by-side.' It clearly distinguishes from the sibling ai_visibility_check by focusing on side-by-side comparison of multiple entities and explicitly mentions ranking and output details.

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

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

The description provides clear context: 'Useful for competitive AI-marketing audits' with an example question. It implicitly distinguishes from single-entity tools by saying it probes each entity and ranks them, but it does not explicitly name an alternative tool or state when not to use it.

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

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

Beyond the readOnly/idempotent/destructive annotations, the description discloses important behavioral details: the composite nature, sources queried, partial failure degradation, bundlephobia's first measurement can take 5-30 seconds, and that sources_failed will list timeouts. It also details the return structure (summary block fields, links, alternative versions). No contradiction with annotations exists.

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

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

The description is a single dense paragraph but every sentence contributes useful information—purpose, use case, sources, return data, ecosystem limit, failure mode. It is front-loaded with the core purpose, though structuring the return fields or timeout caveat as bullets could improve scannability. Overall it is appropriately sized and not wasteful.

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

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

For a composite tool with no output schema, the description generously explains return values, including a summary block of 10 fields, links, and alternative versions. It also covers failure behavior, ecosystem scope, and timing expectations. Given the tool's complexity, the description is remarkably complete and leaves no major gaps for an agent to invoke it correctly.

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

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

The input schema provides 100% coverage for both parameters, including descriptions and defaults. The description adds some context around the version parameter by mentioning 'version history' and 'recent alternative versions', but it does not significantly elaborate on parameter formatting or behavior beyond the schema. Therefore, a 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 clearly states the tool's purpose: a composite check for evaluating whether to add an npm package, combining deps.dev and bundlephobia data. It is specific about the resource (npm packages) and the verb (scan), and the phrase 'ONE call' distinguishes it from multi-step alternatives. It effectively differentiates from sibling tools like 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?

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also clearly states the ecosystem limitation and directs alternative ecosystems to fall under deps.dev:version directly. This provides both when-to-use and when-not-to-use context, satisfying the dimension fully.

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

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

Annotations already mark it as read-only and idempotent, and the description adds valuable behavioral detail: returns offsets for verification, uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, and has a 200K char truncation cap that is flagged. 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 concise and front-loaded, starting with the core function. Every sentence earns its place: input/output, use case, pairing with a sibling tool, and technical constraints. 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?

Even without an output schema, the description explains return values (passages with character offsets and similarity scores) and important edge behavior (truncation flagged). This is complete for the tool's moderate complexity.

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

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

Schema coverage is 100% with detailed descriptions for text, query, and limit. The description adds some context like 'e.g. a SEC 10-K body' and 'top-N passages,' but these mostly reinforce rather than substantially extend the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool performs semantic search inside a previously fetched record, with specific outputs (top-N passages, character offsets, similarity scores). It distingishes from siblings by explicitly pairing with ask_pipeworx_grounded and contrasting grounding over relevant passages vs. the whole document.

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

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

Provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt.' It also names an alternative workflow with ask_pipeworx_grounded and explains how search_within fits in, making both the use case and the alternative 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 non-read-only and idempotent behavior. The description adds valuable specifics: OAuth requirement, phone verification for SMS, 10/day cap, always-on feed with retrieval methods, and webhook auto-disable after 10 consecutive failures. No contradiction found.

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

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

The description is well-structured: purpose first, then prerequisites, types, and delivery channels. It is fairly long but information-dense with no fluff; every sentence earns its place, though some redundancy with the schema exists.

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

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

Covers return value (subscription ID), auth prerequisites, delivery channels, and rate limits. It omits two schema enum types in the prose and lacks error-handling details, but for a subscription creation tool it is quite 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%, but the description enriches semantics with concrete examples (e.g., items:['5.02'] = officer change) and delivery constraints (phone verification, webhook HMAC signing). However, the 'Supported types' list omits patent_grant and clinical_trial which appear in the schema enum, slightly limiting completeness.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource, distinguishing it from sibling tools like list_subscriptions and unsubscribe. It also enumerates supported types and returns the new subscription ID.

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 clear context: requires a Pipeworx OAuth account, lists supported subscription types with examples, and describes delivery channels. It does not explicitly mention when not to use or alternatives, but the intended usage is unambiguous.

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

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

Annotations already cover safety and read-only aspects. The description adds behavioral details: it returns category-bucketed examples from a live catalog, supports no-arg calls for full spread, and accepts an optional topic to focus. It also discloses its role as an entry point for learning meta-tools. 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 a single dense paragraph that front-loads with a long list of rhetorical questions (e.g., 'What can I ask Pipeworx? ... give me ideas'), which is redundant and could be condensed. The core information is present, but the verbosity slightly detracts from scannability.

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

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

For a tool with one optional parameter, no output schema, and strong annotations, the description fully covers behavior: it explains the return content (category-bucketed examples with tool+argument shapes), the effect of omitting vs. passing 'topic', and the intended use as an onboarding aid. No gaps remain for an agent to invoke it confidently.

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 fully describes the optional 'topic' parameter including allowed values and omission behavior (100% coverage). The description adds only minor examples ('finance', 'pharma', 'betting') that align with the schema's enum-like list, providing no significant new meaning beyond the schema.

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

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

The description clearly identifies the tool as the onboarding entry point for discovering what questions can be asked, and specifies that it returns category-bucketed example questions with tool+argument shapes. It distinguishes itself from siblings by explicitly referencing meta-tools and framing itself as the first step, making the purpose specific and actionable.

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 instructs to 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This provides strong when-to-use context and hints at when not to use it (i.e., when you already know what to ask), giving clear guidance relative to 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 indicate destructiveHint=false and idempotentHint=true, but the description adds critical context: ownership enforcement, deactivation rather than deletion, and preservation of historical events via recent_alerts. This goes beyond the structured annotations and clarifies side effects.

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

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

The description is two concise sentences, front-loaded with the action. Each sentence adds essential information: ownership and deactivation behavior. 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?

For a single-parameter tool with no output schema, the description fully covers purpose, safety, side effects, and data preservation. It even links to recent_alerts for historical data, making it self-contained.

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

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

Schema coverage is 100% and the description of 'id' is already provided in the schema. The description adds minimal parameter guidance beyond 'by id,' so the baseline score of 3 is appropriate.

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

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

The description opens with 'Cancel a subscription by id,' a specific verb+resource action. It distinguishes itself from sibling tools like subscribe and list_subscriptions by detailing ownership enforcement and the soft-delete 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?

The description clearly implies when to use the tool (to cancel a subscription) and provides context via ownership and deactivation semantics. It does not explicitly state exclusions or alternatives, but the context is sufficient for selection among 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description details the internal pipeline: structured SEC EDGAR path for financial claims, grounded pipeline for others, and the exact output (verdicts, evidence, reasoning). This adds meaningful context about behavior without contradicting any 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 somewhat long but every sentence contributes: trigger phrases, use case, routing, and outputs. It is front-loaded with the most actionable information and avoids redundancy, though it could be tightened slightly.

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

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

For a tool with no output schema, the description is thorough: it explains what it returns (verdict types, evidence, reasoning), when to use it, and how routing works. Minor gaps like latency/cost are non-essential, and the tool's complexity is well covered.

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% for both parameters via the input schema, and the description itself doesn't need to add parameter details. The schema already explains 'claim' and 'tolerance_pct' well; the description's mention of percent-delta math is supplementary but not required.

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 natural-language claim verification against authoritative sources, with trigger phrases ('fact check', 'verify the claim that...') that make its purpose unmistakable. It also distinguishes itself from sibling tools like ask_pipeworx or deep_research by focusing on verifying whether something a user said is factually correct.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides routing logic for financial vs. other claims. It doesn't name alternative tools, but the trigger phrases and 'Replaces 4–6 sequential calls' give strong contextual guidance on when to invoke it.

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