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 behavior, so the bar for additional disclosure is lower. The description still adds valuable behavioral context: routing is automatic, arguments are filled, citations are stable, it works on every tier, and it can serve as the default single call.

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: preference rationale, domain list, concrete examples, default positioning, and escalation to siblings. It is front-loaded with the strongest directive ('PREFER OVER WEB SEARCH'), though a few phrases could be trimmed without losing meaning.

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 routing tool with no output schema, the description is remarkably complete. It covers when to use, what kinds of questions, concrete examples, alternative tools, edge cases like breaking news, and output characteristics. An agent has enough context to invoke it correctly as the default for factual questions.

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% and the schema already documents 'question' plus aliases clearly. The description adds natural-language question examples and domain categories, but doesn't materially deepen the understanding of individual parameters beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('routes the question') and resource ('5,706 tools across 1493 verified sources') and clearly states the output: structured answers with pipeworx:// citation URIs. It also distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research and positioning itself as the default entry point.

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

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

Provides explicit when-to-use guidance ('Use whenever the user asks...') and explicit escalation rules: use ask_pipeworx_grounded for hallucination-resistant single answers, and deep_research for broad/multi-part questions. It also preempts web search by stating it should be preferred for these factual categories, leaving no ambiguity.

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

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

Beyond the annotations, the description reveals crucial live behavior: candidate routing improvements are enabled only when under test, no candidate is currently active, and it currently matches ask_pipeworx exactly. It also clarifies there is no fallback—'this IS a full working router'—which meaningfully prevents an agent from assuming degraded behavior.

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

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

The description is front-loaded with the essential identity, then the current live state, then usage guidance, and then a clarifying fallback statement. Every sentence contributes distinct information, and the structure is easy for an agent to parse quickly.

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 router tool with a single required natural-language argument and no output schema, the description is complete: it explains current behavior, equivalence to ask_pipeworx, experimental status, and how results are used. An agent has everything needed to invoke it correctly and interpret its relationship to the stable router.

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 documents all parameters with 100% coverage, including aliases, so the description does not need to repeat them. The description adds only the high-level 'same arguments' reference to ask_pipeworx, which is useful but not necessary beyond the schema's thorough coverage.

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

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

The description is explicit: this is a 'Beta version of ask_pipeworx' and a 'universal router' with the same 5,706 tools, arguments, and response shape. It clearly distinguishes itself from the stable ask_pipeworx by emphasizing candidate routing improvements and the experimental edge, so an agent can identify what the tool does without opening the schema.

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

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

It gives direct usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the comparison against the stable router. However, it does not explicitly state when NOT to use it or name an alternative such as ask_pipeworx_grounded, leaving some exclusion condition implied rather than stated.

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 the exact success return shape, the exact refusal return shape with refusal reason enum values, and the key behavioral constraint of using only tool-result content. This goes well beyond the readOnly/idempotent annotations and fully explains what the agent should expect.

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 yet organized: it opens with the core purpose, then explains behavior, return contracts, use cases, and the tradeoff against the sibling. Every sentence contributes necessary decision-making information without padding.

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

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

Despite lacking an output schema, the description fully compensates by documenting both success and failure return shapes, refusal reasons, and behavioral guarantees. Combined with the annotations, an agent has everything needed to invoke the tool correctly and interpret its result.

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

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

Schema description coverage is 100%, with the question parameter and all aliases documented in the schema. The description adds high-level context about the kind of questions to ask but does not need to repeat parameter details, so the baseline of 3 is appropriate.

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

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

The description clearly identifies a specific mode: a hallucination-resistant, grounded answer extractor that routes like ask_pipeworx but extracts answers only from tool results. It differentiates itself from the ask_pipeworx sibling by emphasizing evidence, refusal behavior, and high-stakes use.

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 this tool when answers will be quoted, cited, or acted on, and prefer ask_pipeworx for casual lookups. It also names the cost tradeoff—one extra LLM call—so an agent can make a deliberate choice between 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?

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?

Annotations already mark this as read-only, idempotent, and non-destructive, but the description adds substantial behavioral detail: parallel facet routing, gap-reporting with no invented answers, contradiction scanning, semantic excerpting of large records, citation fetchability guarantees, and expected latency ranges. This goes well beyond what the structured annotations reveal.

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

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

The description is dense and long, but almost all content is relevant and front-loaded with the account requirement and primary alternative before explaining mechanics. Minor redundancy exists between the 'stable pipeworx:// citation per finding' phrase and the later detailed citation_uri explanation, though the overall structure remains scannable and purposeful.

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 compensates by detailing the findings packet contents, gap reporting, contradiction arrays, hop field, citation URI behavior, and latency expectations. It also covers prerequisites, costs, and clear alternatives, making the tool effectively usable without requiring the agent to inspect further 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?

Although schema coverage is 100%, the description adds meaning beyond the schema by explaining that depth:'thorough' requires a paid plan, and by detailing how standard and thorough depth levels handle gap recovery and lead-chasing. It also clarifies that question may be broad and multi-part, reinforcing the intended usage of the required parameter.

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 a specific verb and resource: deep_research performs grounded multi-source research across Pipeworx's 1,493 structured data sources, decomposing questions into facets and running parallel tool calls. It explicitly distinguishes itself from open-web search and from ask_pipeworx, so an agent can readily tell what it does and what it is not.

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

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

The description gives explicit when-to-use guidance: best for broad/multi-part structured-data questions, use ask_pipeworx for single lookups or breaking/current-news topics, and use ask_pipeworx if not signed in. It also specifies account and paid-plan prerequisites, leaving little to inference.

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 minimal (all false), but the description discloses substantial behavior: the claim_token flow (filing without an account returns a token; passing it back later reads resolution status), rate limiting ('Rate-limited to 5 per identifier per day'), and cost ('Free; doesn't count against your tool-call quota'). 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?

Though longer than typical, every sentence delivers unique information: scope, exclusions, types, claim-token workflow, rate limit, quota impact. It's front-loaded with the primary action and organized logically.

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

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

The tool has 4 params, nested objects, no output schema, but the description explains return behavior (claim_token and later resolution status), required context (none), and how to use each parameter in context. Sufficient 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?

Schema coverage is 100% (baseline 3), but description adds lifecycle context for claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and clarifies the meaning of each type beyond the enum descriptions, e.g., 'data_gap = data Pipeworx does not currently expose.' This lifts it above baseline.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist' and enumerates feedback types (bug, feature, data_gap, praise). It clearly distinguishes from siblings like ask_pipeworx or discover_tools by defining its unique role as the 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?

Explicitly states when to use ('Use when a tool returns wrong/stale data...') and when not to ('ONLY for tools served by this Pipeworx connection... file it with that server instead'). Also advises how to disambiguate via 'Pipeworx tool names are the ones this connection lists.'

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

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

Annotations already 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?

Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: response shape, compatibility_codes, per-leg flags, skipped comparison categories, temporal alignment, and the important warning that unclassified legs are never paired. No statement contradicts the annotations.

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

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

Although the description is long, it is densely structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS) and each sentence adds operational value. The most important caveat about pre-mapped topics not being tradeable is placed at the end but is clearly flagged, and no filler or repetition is 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?

This is a complex tool with no output schema, so the description carries the full burden of explaining return values, safety fields, edge cases, and how to interpret spreads. It covers all of these extensively: top_spreads_pp, compatibility codes, skipped_unclassified, low_confidence_pairs, temporal_alignment, and the counters for dropped comparisons. Nothing essential for correct invocation or interpretation is missing.

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

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

Schema coverage is 100%, but the description meaningfully extends the schema by explaining that topic is a pre-mapped shortcut that auto-fetches matching events, and that explicit ticker/slug parameters override the topic-mapped side. It also clarifies the semantics of pre-mapped pairing reliability, which is not inferable from parameter names alone.

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

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

The description states a specific verb and resource: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, including two distinct input modes. It is clear and concrete, but it does not explicitly contrast itself with sibling tools like polymarket_arbitrage, so differentiation from siblings is implied rather than 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?

The description gives practical usage context: topic mode for pre-mapped shortcuts, explicit ticker/slug mode for custom pairings, and a caveat that pre-mapped topics often return compatibility warnings. It does not name alternative tools or say when not to use this tool, but the mode guidance and tradeability warning provide clear operational direction.

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

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

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?

The description richly discloses behavioral traits beyond annotations: it cascades through multiple endpoints, degrades gracefully (GLEIF/OpenFIGI unavailability doesn't break EDGAR results), labels identifiers with source, and explicitly states unresolved identifiers. Annotations (readOnly, idempotent, openWorld) are consistent and complemented by this detail.

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

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

The description is verbose and packs extensive detail, but it's not as concise as it could be. The first sentence effectively front-loads use cases, but subsequent sentences could be tightened. Some redundancy exists (e.g., repeating the supported types in multiple forms).

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

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

Given the tool's complexity (multiple entity types, cascading lookups, graceful degradation, unresolved identifiers), the description is thorough. It covers what the tool does, how it behaves under failure, and what information is returned. However, there is no output schema, so the description partially compensates but doesn't fully specify the exact response structure.

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

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

Schema coverage is 100%, but the description adds significant meaning: for the 'type' enum, it explains what each resolves to (company gives CIK, ticker, LEI, etc.; drug gives RxCUI). For 'value', it gives examples (ticker, CIK, ISIN, brand names) and explains edge cases like ISIN-to-LEI mapping. This is far beyond the schema's brief descriptions.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers. It provides specific examples like ticker, CIK, LEI, and RxCUI, and lists supported types (company, drug). This distinguishes it from sibling tools like compare_entities or entity_profile, which serve different purposes.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', which is strong guidance for when to use this tool. It also implies it replaces multiple manual lookups. However, it does not explicitly state when not to use it or mention alternatives, leaving room for slight ambiguity.

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?

Adds critical behavioral context beyond the annotations: defines the six verdict values, clarifies that could_not_verify means the check did not happen (not evidence), and explains unsupported. It also mentions internal routing and evidence citation, going well beyond the readOnly/openWorld/idempotent hints.

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

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

The description is well-structured: usage examples first, then functional overview, then return semantics, then important caveats. Despite its length, every sentence adds value and it is easy to parse.

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

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

With no output schema, the description carries the full burden for return values. It fully specifies the verdict enum, citation format, reasoning, and error handling, and covers both company-financial and general factual claims with routing details. It is complete for the tool's complexity.

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

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

Schema coverage is 100% with detailed parameter descriptions, including tolerance_pct semantics and defaults. The main description does not further elaborate on parameters, though 'exact percent-delta math' indirectly relates to tolerance.

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 natural-language claim verification against authoritative sources, with query examples like "fact check" and "verify the claim that…". It also distinguishes between company-financial claims (SEC EDGAR fast path) and other claims, setting it apart from sibling tools.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and notes it replaces 4–6 sequential calls. However, it does not name alternative tools or state when not to use it, so it lacks exclusion guidance.

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