Usaspending

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds beyond annotations by explaining the default model (free), the optional Anthropic probing (with cost implications), and the return structure (per-model score, confidence, signals, raw_response, combined view). No contradictions.

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

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

The description is 4-5 sentences, front-loaded with the core purpose. Every sentence provides essential information: what it does, default behavior, optional features, return format, and use cases. 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?

Given 4 parameters (100% schema coverage), no output schema, and no nested objects, the description covers purpose, usage, parameter details, and return format sufficiently. It explains the default model, optional Anthropic, and the output structure, enabling an agent to 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%, so baseline is 3. The description adds meaning: it explains that 'models' defaults to 'workers-ai' and that '_apiKey' is needed for Anthropic, with the note 'BYO key — you pay Anthropic directly.' It also clarifies that 'context' helps disambiguate. This adds value beyond the schema.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100). It specifies the verb 'probe' and the resource 'LLMs', and differentiates from siblings like 'ask_pipeworx' (which queries a specific system) and 'scan_competitor_ai_presence' (which may be broader). The mention of default model and optional Anthropic adds clarity.

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 advises use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It implies when to use but does not explicitly mention when not to use or compare with alternatives. However, the context is clear enough for an agent to decide, especially with sibling tools like 'scan_competitor_ai_presence' available.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds meaningful context: it reveals routing behavior, argument filling, citation URIs, tier-universal availability, and 'one fast call' performance. 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 front-loaded with the key directive and includes helpful examples, but it is long and somewhat repetitive (e.g., the extensive domain list and example queries). Each section serves a purpose, but it could be tightened 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?

For a routing tool with no output schema, the description is remarkably complete. It covers supported domains, example queries, usage priority, sibling differentiation, tier support, and when to step up. An agent has everything needed to decide when 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% – all six parameters are aliases with descriptions, and 'question' is well-documented. The description does not add parameter-level detail, but the schema fully handles it, so the baseline of 3 applies.

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

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

The description clearly states the tool's function: it routes questions to 5,529 tools across 1,455 verified sources and returns structured answers with citation URIs. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives, and includes concrete examples of what it can answer.

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 provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' and 'Use whenever the user asks...' listing trigger phrases. It also specifies when to use alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'.

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 adds significant behavioral context beyond annotations: it discloses the tool's experimental nature, that it may have candidate routing improvements active at times, and that it is a full working router with no fallback. This goes well beyond the readOnly/openWorld/idempotent hints and gives the agent a realistic picture of its 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 four sentences, all dense with useful information: beta status, identity, current state, usage, and purpose. It is front-loaded with the key identifier 'Beta version of ask_pipeworx' and omits any fluff or unnecessary 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?

The description is highly complete given the tool's complexity, explaining the experimental routing, current parity with ask_pipeworx, and its role in A/B testing. It relies on the sibling tool for the exact response shape, but since ask_pipeworx is available as a sibling, this is an acceptable shortcut. A full description of the response shape would make it perfect, hence the 4.

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 provides 100% description coverage for all parameters, so the baseline is 3. The description only adds 'same arguments' which is redundant given the schema already lists all aliases. It does clarify compatibility with ask_pipeworx, but this is minor and doesn't deepen semantic understanding beyond the schema.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It distinguishes from the stable ask_pipeworx by emphasizing the experimental routing improvements, making the purpose and scope unambiguous.

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

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

Explicitly instructs users to 'Use it exactly like ask_pipeworx when you want the newest routing' and mentions results are compared against the stable router. This provides clear direction on when to use this tool versus the stable alternative, and notes the current state (no active candidate) so users know it behaves identically right now.

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 hints, but the description adds significant behavioral detail: the extraction is strictly from tool results, refusal_reason enums are listed, and the output shape is described. It also mentions the extra LLM call cost versus ask_pipeworx. 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 compact yet information-dense. It front-loads the core value proposition, then systematically covers behavior, return format, usage guidance, and cost tradeoff—all in about 90 words. Every sentence contributes unique information, 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?

With no output schema, the description fully defines the success and refusal response shapes, including specific refusal reasons. It also covers cost implications and provides examples of high-stakes use cases. Given the tool's complexity and the absence of an output schema, this description is exceptionally 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?

The schema already provides 100% description coverage for all six parameters (all aliases for 'question') with clear descriptions. The tool description adds no further parameter-level semantics, but given the high schema coverage, 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 opens with 'Hallucination-resistant answer mode for high-stakes reads,' clearly identifying the tool's purpose as a grounded extraction variant of ask_pipeworx. It distinguishes from the sibling by explicitly mentioning the use of only tool-result content and the refusal mechanism, 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?

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also contrasts with ask_pipeworx by advising 'prefer ask_pipeworx for casual lookups' and citing the extra LLM call cost, fulfilling both when and when-not usage.

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

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

The description goes far beyond annotations, detailing resolver contract, parent event extraction, news fallback, safety short-circuits, closed market handling, wide spread warnings, and cancellation rules. 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 very long and verbose, packed with examples and details. However, it is well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES) and front-loaded with purpose. It could be more concise but earns a 3 for structure.

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

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

Given the tool's complexity (no output schema, multiple features), the description is extremely thorough, covering resolver contract, parent event, news handling, safety checks, and edge cases like closed markets and cancellation rules. No aspect is left unexplained.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant meaning: how to pass market (slug/URL/text), depth parameter (quick vs thorough with specifics), and include_raw (summarized vs full payloads with rationale).

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 researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on a single bet research.

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

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

Explicit use cases are given: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It does not explicitly state when not to use, but the purpose is clear enough to avoid misuse. Alternatives are implied by sibling list.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. 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 slightly long but front-loaded with trigger phrases that help an agent quickly identify when to use it. Every sentence adds essential information; can be justified despite length.

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

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

Given no output schema, the description compensates by detailing return format (paired data, citation URIs, sorted by primary metric) and data sources. It covers both entity types, special cases (off-calendar fiscal years), and limitations (2-5 entities). 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%, so baseline is 3. The description adds meaning by explaining the data pulled for each type (e.g., revenue, net income for companies; adverse-event counts for drugs) and giving example inputs. This goes beyond the schema's enum and array descriptions.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call, with specific query triggers like "Compare X and Y". It differentiates between entity types and data sources, and contrasts with sequential lookups from sibling tools like entity_profile.

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

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

The description explicitly advises to prefer this tool over sequential single-pack lookups when comparing entities, providing strong usage guidance. It does not detail when not to use it, but the context is clear enough for correct selection.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds far more: the parallel routing pipeline, the findings packet structure (verbatim evidence + confidence + source + fetched_at + pipeworx:// citation), gaps[] for unanswered facets, never-invented policy, contradiction scans, semantic excerpting of large records, hop fields, fetchable citation URIs, and latency expectations. It even discloses account/payment requirements. This is rich, trust-building behavioral detail beyond any hint.

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

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

The description is long but front-loaded with the most critical info (account requirement and fallback to ask_pipeworx). Each paragraph adds non-redundant content: use cases, exclusions, depth behavior, result format, and time expectations. It could be more skimmable with bullet points, but no sentence is fluff. Score 4 rather than 5 due to the wall-of-text format.

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

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

For a tool with no output schema, the description fully compensates: it enumerates the exact return fields (verbatim evidence, confidence, source, fetched_at, citation_uri), explains gaps[] and contradictions[], states that large records are semantically excerpted, and predicts latency ranges. It also covers prerequisites (sign-in, paywall for thorough), alternatives, and known limitations (current news). Nothing important is left unexplained.

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

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

Input schema covers 100% of parameters, so baseline is 3. The description adds meaning by explaining operational differences between depth levels ('standard' adds gap-recovery hop + contradictions[]; 'thorough' adds lead-chasing and requires paid) and explicitly invites 'Broad/multi-part is fine' for the question parameter. This contextual elaboration raises it to 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 states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources (SEC filings, FRED/BLS economics, FDA, USPTO patents, markets, science, government records, etc.) in ONE call—this is NOT open-web search.' It distinguishes from siblings by naming ask_pipeworx for single lookups and current news, and gives concrete examples of broad multi-part questions. This is far beyond a tautology.

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 present: 'For a single lookup use ask_pipeworx (one LLM call, not many)', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead.' It also clarifies that deep_research is best for broad/multi-part structured-data questions and explains when depth:'standard' vs 'thorough' should be chosen. This is a model of when-to-use and when-not-to-use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful context: results are 'ready to call directly, no second schema lookup needed.' It does not contradict annotations.

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

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

The description is dense but front-loaded with purpose. It lists domains compactly and includes key behavioral details. A bit long but each sentence adds value. Could be more structured, but overall concise.

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

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

Given 6 parameters, no output schema, and complexity, the description covers what the tool does, what it returns, and when to use it. It could mention if it returns suggested questions or only direct matches, but it's sufficient for an agent to use correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description reinforces that 'query' accepts natural language and lists aliases, which adds some redundancy but also provides examples and context that enhance understanding.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many specific domains (SEC filings, drugs, etc.) and explains what it returns (top-N relevant tools with names, descriptions, full input schemas). This distinguishes it from sibling tools that perform specific actions.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear guidance on when to use it. It doesn't explicitly say when not to use or name 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 readOnlyHint, openWorldHint, idempotentHint, and non-destructive. Description adds rich behavioral context: fans out across multiple sources, soft-fail for patents, news fallback, and input constraints. No contradictions.

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

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

One paragraph but front-loaded with query examples and efficient in conveying many details. Could be slightly more structured but still concise and scannable.

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 multi-source tool with no output schema, the description covers all major aspects: sources, return fields, fallbacks, limitations, input format. Comprehensive enough for an agent to use correctly.

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

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

Schema coverage is 100% with descriptions. Description adds context by explaining why names are not supported, giving input examples, and noting the type constraint. Adds value beyond schema.

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

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

The description clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call' and lists specific data sources and return fields. It distinguishes from sibling tools like resolve_entity by noting when to use each.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and advises using resolve_entity if only a name is available. Provides clear when-to-use and alternative guidance.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, but does not elaborate on side effects or permission requirements. Adequate but not rich.

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

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

Two sentences, first sentence front-loads the purpose. Extremely concise with no extraneous information.

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

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

For a simple tool with one parameter and annotations covering destructive and idempotent behavior, the description is complete. Could mention error handling for missing key, but not strictly necessary.

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 itself describes the 'key' parameter sufficiently. The description does not add further detail beyond what the schema provides.

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

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

The description clearly states the verb 'Delete' and the resource 'previously stored memory by key', 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?

Provides explicit when-to-use scenarios: stale context, completed task, clearing sensitive data. Also mentions pairing with 'remember' and 'recall', guiding the agent on related tools.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, which the description reinforces by describing the fetch-and-extract process. The description adds behavioral context beyond annotations (e.g., 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format'), though it lacks mention of error handling or rate limits.

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

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

The description is a single focused paragraph with a clear front-loaded sentence followed by a use-case list. Every sentence adds value, and there is no redundancy or filler. It is highly succinct while conveying all necessary information.

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

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

Despite lacking an output schema, the description adequately explains the output as a single text blob and its deployment location. The tool is simple (two parameters, one required), and annotations cover safety. Missing edge cases like error handling are minor given the tool's straightforward nature.

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's main text does not add new parameter information beyond the schema; it only restates the purpose of URL and max_links in the description text. No additional syntax or constraints are provided that aren't already in the schema.

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

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

Description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb, resource, and output format. It distinguishes well from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing on the specific llms.txt generation task.

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?

Description explicitly lists three use cases (client's site indexing, own project drafting, competitor auditing), providing clear context for when to use. It does not explicitly state when not to use or name alternatives, but the sibling tool list and context implicitly differentiate.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds value by specifying the return structure (id, type, params, etc.) and the optional include_inactive parameter 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?

Two sentences with no wasted words. The first sentence states purpose and return fields; the second gives usage guidance. Front-loaded and 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?

For a simple tool with one optional parameter and no output schema, the description covers purpose, return structure, parameter, and usage context completely.

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 one parameter include_inactive described in the schema. The description does not add additional meaning beyond the schema, so 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 states 'List the caller's active subscriptions' with a specific verb and resource, and lists the returned fields. It clearly differentiates from sibling tools like subscribe and unsubscribe.

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

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

The description provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It does not specify when not to use, but the context is clear.

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

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

Despite annotations indicating a non-read-only, non-idempotent operation, the description adds valuable behavioral context: the claim_token mechanism for anonymous feedback, rate limiting (5 per identifier per day), and that feedback directly affects roadmap. It also discloses that the team reads digests daily. This goes well beyond what annotations provide and surfaces important side effects and constraints.

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 a typical two-sentence tool description, but every sentence contributes new, non-redundant information—purpose, usage triggers, exclusion boundary, framing guidance, claim_token flow, team behavior, rate limit, and cost. It is front-loaded with the core purpose and organized logically, though a touch verbose for an agent to parse.

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

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

For a tool with 4 parameters, a nested context object, and no output schema, the description is remarkably complete. It explains the full lifecycle of a feedback report (submission, claim_token, later read-back), the semantics of each feedback type, the limitation on which tools are eligible, and operational constraints like rate limits and cost. No critical information appears 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?

The input schema already has 100% field-level descriptions, so the baseline is 3. The description adds extra meaning by explaining how to use claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and by providing real-world examples for the 'type' parameter (bug, feature, data_gap, praise). This supplemental guidance pushes the score 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-plus-resource statement ('Tell the Pipeworx team something is broken, missing, or needs to exist') and clearly distinguishes itself from sibling tools like ask_pipeworx by scoping its purpose to feedback rather than questions. It also explicitly enumerates the categories of feedback (bug, feature/data_gap, praise), leaving no ambiguity about what the tool does.

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 for each feedback type and a concrete when-not-to-use exclusion: if a tool came from a different MCP server, file with that server instead. It also provides instructions on how to frame the feedback (in terms of Pipeworx tools/packs, not user prompts) and how to use claim_token for follow-up, which is strong alternative/usage guidance.

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

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

Annotations already declare safe, read-only, idempotent behavior. Description adds caching details ('Cached 5min-1h depending on window'), data source ('CF analytics-engine'), and PII assurance, which are valuable 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?

Well-organized with bullet points and clear sentences. Every sentence adds value, though slightly verbose; still efficient for the amount of information conveyed.

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

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

Given one optional parameter, no output schema, and comprehensive annotations, the description covers what the tool does, when to use, data origin, caching, and privacy. Complete enough for an agent to confidently select and invoke.

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?

Only one parameter (window) with 100% schema coverage. Description adds meaningful context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' which aids selection beyond the enum list.

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

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

Description clearly states it returns 'top tools, top packs, and total call volume over a recent window' with specific time options. Verbs and resource are unambiguous, and it distinguishes its trending focus from sibling tools like discover_tools.

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

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

Provides three explicit use cases (discovering hot data sources, confirming canonical tool, aligning use case). While it doesn't explicitly state when not to use, the context is sufficient for typical decision-making.

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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds extensive behavioral details: partition checks, semantic anchor, fill check logic, and response structure. No contradiction.

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

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

The description is long but well-structured with clear sections and examples. Front-loaded with main purpose. Could be slightly more concise but organized effectively.

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 complexity, description covers all necessary aspects: response format, edge cases (placeholders, similarity), fill check, and references polymarket_fill_risk for custom sizing. No output schema, but response fields are explained.

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. Description adds significant value: explains event slug examples, topic seed examples, and the behavioral difference between event and topic modes. Not maximally concise but highly informative.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between no-arg trending scan, event mode, and topic mode, differentiating it from siblings like polymarket_edges.

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

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

Explicitly states when to use each parameter: call with no args for trending scan, pass event for specific market (recommended), pass topic for cross-event scan. Also mentions when not to trade via fill check.

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

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

The description extensively discloses behavioral traits beyond annotations: model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), tradeable-edge knobs, caching (1h at KV level), response structure with diagnostics, and Fed bets handling. 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 clear sections and front-loaded purpose. Every sentence adds unique value given the tool's complexity. Minor conciseness improvement could be made but it earns its length.

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

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

Despite no output schema, the description fully details response structure (by_segment, fed_candidates, _diagnostics), key metrics (edge_pp_net, kelly_fraction, market info), and caching behavior. It is complete for effective agent decision-making.

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 decent descriptions, but the description adds significant value by explaining interactions (e.g., min_partition_leg_kelly vs min_kelly, slippage rationale, tradeable-edge filters). It deepens understanding beyond schema labels.

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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, explicitly positioning it for 'what should I bet on today'. It distinguishes from siblings by focusing on Pipeworx disagreement and discovery without paging.

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

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

The description explains when to use it (discover opportunities, top markets, daily use) and provides detailed guidance on parameter knobs. However, it does not explicitly contrast with siblings like polymarket_arbitrage or polymarket_edge_tracker, though the context of sibling names implies 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, idempotentHint, and destructiveHint appropriately, so the safety profile is clear. The description adds detailed behavioral context: response structure, snapshot availability, and decay computation, exceeding what annotations provide.

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

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

The description is well-structured: opening purpose, detailed response breakdown, and limits. While slightly verbose, each sentence adds value, and the structure aids readability.

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

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

Given no output schema, the description fully explains the response fields (tracked, expired, snapshot_dates) and behavior. All parameters are documented. Contextual completeness is high.

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

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

Input schema covers both parameters with descriptions, achieving 100% coverage. The description adds minor context (e.g., 'snapshot family' for window) but largely repeats schema information. 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's purpose: analyzing edge persistence and decay from daily polymarket_edges snapshots. It differentiates from sibling tools by emphasizing that a fresh wide edge and a 3-week-old wide edge are different trades, implying this tool provides historical context not available from other 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 gives clear context on when to use the tool (e.g., to assess how long an edge has existed and if it's decaying). It includes limits (60-day TTL, snapshot gaps) but does not explicitly state alternatives or when not to use it.

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

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

Annotations already indicate read-only, open-world, and idempotent; description adds rich behavioral detail: walks the order ladder, returns specific data fields (top_of_book, vwap_fill_price, slippage, shares_filled, etc.), and warns about risks (thin_legs, forced_directional_risk). No contradictions.

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

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

Well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET) and bolded keywords. Slightly verbose but each sentence adds value; no fluff.

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

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

Despite no output schema, the description fully enumerates return fields for both modes, explains edge cases (thin books, partial fills), and provides rationale for usage. Complete for a pre-trade risk check 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 covers 100% of parameter descriptions, but the tool description adds contextual meaning beyond schema (e.g., size_usd interpretation for buys vs sells, basket auto-side logic, mutual exclusivity of market/event). Minor improvement over 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?

Clearly states it performs a realizable-vs-theoretical edge check against live CLOB depth. Distinguishes between single-market and basket modes, and explicitly contrasts with sibling tools by noting it is a pre-trade risk 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?

Explicit usage instruction: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains rationale and constraints (mutual exclusion of market/event, defaults, clamping).

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

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

The description goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by detailing compatibility_warning scenarios (non-equivalent bet shapes, semantically unrelated events), temporal alignment, and skipped comparison counters. This disclosure of limitations and failure modes adds significant transparency beyond what annotations provide.

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

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

The description is moderately concise but could be trimmed without losing meaning. It front-loads the core purpose, then explains modes, response, and safety fields. However, there is some redundancy (e.g., repeatedly mentioning that most topics return warnings). It is structured but slightly verbose for a summary description.

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

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

Given the complexity (cross-venue spread with compatibility checks and no output schema), the description adequately covers the return format (leg-by-leg prices, matched spreads, safety fields) and parameter usage. It explains temporal alignment and skipped types, leaving few gaps. A small example or diagram of output structure would improve completeness, but it is largely sufficient.

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 all 3 parameters, with detailed descriptions in the schema. The description adds context about the two modes and provides examples, but does not add meaning beyond what the schema already describes. Baseline 3 is appropriate as 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 it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on cross-venue comparison. The two modes (topic shortcuts and explicit tickers) are explicitly defined.

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 on when to use each mode (topic for common macro shortcuts, explicit tickers for custom pairs). It warns that most pre-mapped topics return compatibility warnings, indicating when the tool may not be useful. However, it does not explicitly exclude alternatives or state when to use sibling tools instead.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description reinforces safe behavior. It adds value by disclosing scoping (anonymous IP, key hash, account ID) and pairing expectations, which go beyond what annotations provide.

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

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

Description is only three sentences, with the most important action and usage upfront. Every sentence adds value: action, use cases, scoping, and 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?

Given the simple one-param tool with annotations covering safety and idempotency, the description fully covers behavior, scoping, and usage pattern. No output schema needed; return is implied. All signals (completeness, sibling context) are well addressed.

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

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

Schema coverage is 100% with the parameter description already stating 'omit to list all keys'. The description does not add new parameter-level meaning beyond the schema, so 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?

Description clearly starts with verb 'Retrieve' and specifies two modes: get a specific value by key or list all keys. It distinguishes itself from sibling tools 'remember' and 'forget' by explaining the pairing, and provides concrete use cases like ticker or address lookup.

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?

Description explicitly states when to use ('to look up context the agent stored earlier') and advises against re-deriving info. It scopes usage to identifier types. While it doesn't list alternatives explicitly, the sibling context and mention of 'remember'/'forget' provide clear 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 declare read-only, idempotent, open-world, non-destructive. Description adds behavioral details like mark_read affecting subsequent calls and the feed being persisted. No contradictions.

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

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

Four sentences, front-loaded with purpose, efficient, no wasted words.

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

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

Despite no output schema, description explains return fields, filtering, mark_read behavior, and polling suitability. Complete for an agent to use effectively.

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

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

Schema coverage is 100%. Description adds meaning beyond schema: explains returned fields, gives example for type ('sec_8k'), clarifies mark_read effect, and specifies since condition (fired_at >= timestamp).

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 pulls fired events from subscription feed, returns recent alerts with source, citation_uri, and raw payload. Distinguishes from siblings by being specific to alerts feed.

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 guidance on filtering by type and since, setting mark_read, and notes that polls work fine. Mentions alternative access via GET endpoint, but lacks explicit when-not usage.

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

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

Despite annotations already declaring readOnlyHint, openWorldHint, etc., description adds rich behavioral context: fans out to multiple sources with fallback logic (GDELT→GNews), notes USPTO patent soft-fail, and describes return structure (changes[] grouped by source + total_changes + citation URIs). 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?

Description is front-loaded with example queries, then explains mechanics. Every sentence provides useful information, no fluff. Length is justified by complexity of the tool.

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

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

Given the tool's multi-source nature, fallback logic, and no output schema, the description adequately covers all aspects: input parameters, sources queried, fallbacks, return format, and even notes a limitation (USPTO patents soft-fail). Leaves no ambiguity for an agent.

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

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

Schema covers all 3 parameters with descriptions. Description adds value by providing practical examples for `since` (ISO date and relative shorthand like '7d', '30d'), explains `value` can be ticker or CIK, and clarifies `type` is only 'company'. Does not fully repeat schema but enhances it.

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

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

Description clearly states the tool provides a change feed for a company across multiple sources in one parallel call. It gives specific example queries and distinguishes from sibling tool 'entity_profile' which provides static profile.

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

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

Explicitly states when to use this tool (dynamic changes over a window) vs when to use entity_profile (static profile). Provides example queries like 'What's new with X' and explains the window parameter.

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 readOnlyHint=false and destructiveHint=false, so the description correctly implies a write operation that is non-destructive. It adds value by explaining the storage scope (key-value, per identifier) and persistence differences between authenticated and anonymous sessions, beyond what annotations provide.

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

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

The description is appropriately sized, well-structured, and front-loaded with the primary purpose. It provides useful examples and usage context without unnecessary verbosity.

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

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

Given the tool has only two simple parameters, no output schema, and annotations are present, the description sufficiently covers the tool's behavior and usage. It explains storage scope, persistence, and pairing with sibling tools.

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 context by mentioning 'key-value pair' and pairing with recall/forget, but doesn't provide additional detail beyond the schema's parameter 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 defines the tool's purpose as saving data for reuse across conversations or sessions, with specific examples like resolved tickers, target addresses, and user preferences. It distinguishes itself from sibling tools recall and forget, which are explicitly mentioned.

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: 'when you discover something worth carrying forward'. It also provides context for paired use with recall and forget, though it doesn't explicitly state when not to use it.

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

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

Beyond annotations (readOnly, idempotent), the description discloses cross-source identity spine, source labeling, explicit unresolved identifiers, graceful degradation of LEI/FIGI enrichment, and internal multi-endpoint cascading. This adds rich behavioral context.

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

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

The description is detailed and front-loaded with example queries, but it is somewhat long. However, every sentence adds value for a complex tool. It is well-structured and could be slightly more concise without losing information.

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

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

The description fully explains return values for both entity types, including source attribution, unresolved identifiers, and graceful degradation. It covers both input and output semantics thoroughly, compensating for the lack of an output schema.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds operational context (accepted formats and examples) but doesn't add meaning beyond the schema's own description. Baseline 3 is appropriate.

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

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

The description opens with concrete user queries and states a specific verb+resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also distinguishes from siblings with 'Use FIRST whenever you have a name but need an 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?

It explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It also enumerates supported entity types and input formats, and implies it replaces manual lookups. However, it does not explicitly name alternatives or state when-not-to-use.

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

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

Annotations already indicate read-only, idempotent, open-world behavior. The description adds context on the process (probing each entity, ranking) and output structure (score, confidence, signal density), enhancing understanding without contradicting annotations.

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

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

Two concise sentences cover purpose, process, and output. The first sentence front-loads the core function, and every word earns its place without redundancy.

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

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

Despite lacking an output schema, the description fully explains the return value (ranked list with fields). Input schema is fully described. The tool's purpose, process, and output are clearly communicated.

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

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

All 4 parameters have schema descriptions (100% coverage). The description adds semantic value by explaining the first entity as the 'subject' and interpreting models default behavior ('omit for just workers-ai').

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

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

The description uses specific verbs ('compare', 'probes', 'ranks') and clearly identifies the resource ('AI visibility across multiple entities'). It distinguishes from siblings by referencing ai_visibility_check as a sub-tool and framing it for competitive audits.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an illustrative example. It references the sibling tool ai_visibility_check but does not explicitly state when not to use this tool or list alternatives beyond that.

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

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

Annotations already declare readOnly, idempotent, openWorld, not destructive. Description adds rich behavioral details: fans out across deps.dev and bundlephobia, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists failures. 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?

Description is information-dense and front-loaded with main purpose, then details. Every sentence adds value, though slightly verbose. Well-structured for the complexity.

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

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

Given no output schema, description comprehensively covers return value shape (summary block fields, per-advisory detail, links, alternative versions) and failure modes. With clear schema and annotations, the description is fully complete.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds minor context (scoped packages accepted, version defaults to latest) but mostly reinforces schema. No additional syntactic or format details beyond schema.

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

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

Description clearly states the tool does a composite check for npm packages covering license, advisories, version history, bundle size, dependency count, and ESM/tree-shake support. It distinguishes from sibling tools by specifying 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly' and provides explicit usage cues like 'is X safe / popular / small'.

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 instructions ('Use whenever an agent asks...') and warns about partial failures and bundlephobia timeouts. Mentions alternatives for other ecosystems. Lacks explicit when-not-to-use scenarios, but the scope is well defined.

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

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

Annotations already declare readOnlyHint, openWorldHint, etc. The description adds internal details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. This goes well 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?

Three dense sentences: first states purpose, second gives usage guidance, third covers technical limits and return format. No wasted words, front-loaded with the core function.

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

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

Given no output schema, the description still explains return format (passages with offsets and similarity scores). Covers embedding model, chunking, char limit, and integration with a sibling tool. Complete for a search tool.

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

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

Schema coverage is 100%, but the description adds value with natural-language query examples and context that text is a fetched record. This aids understanding 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 starts with 'Semantic search INSIDE a fetched record' and specifies the exact use case (e.g., SEC 10-K, article). It clearly distinguishes from siblings by mentioning the pairing with ask_pipeworx_grounded.

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

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

Explicitly says to use when the record is too big for the prompt and notes the tool saves context. Mentions pairing with ask_pipeworx_grounded, but does not explicitly state when not to use.

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

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

Annotations indicate idempotentHint=true, but the description says 'Returns the new subscription id,' suggesting non-idempotent creation. Additional behavioral details like SMS caps and webhook auto-disable are given, but the idempotency contradiction and lack of clarification on duplicate subscriptions reduce 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 long but every sentence adds value. It front-loads the purpose and packs details. Minor improvement could be structuring with bullet points for readability.

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

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

The description covers purpose, requirements, types, delivery, and return value. Missing details on idempotent behavior and error handling (e.g., what happens on duplicate subscription).

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

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

Schema coverage is 100%, and the description adds substantial value beyond the schema. It provides detailed type-specific examples (e.g., sec_8k items) and delivery constraints (phone verification, SMS cap, webhook signing secret).

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It lists supported types with examples, distinguishing it from siblings like 'unsubscribe' and 'list_subscriptions'.

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

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

The description provides prerequisites (Pipeworx OAuth account), supported types, and delivery channels. It implies monitoring scenarios but does not explicitly contrast with polling tools like 'recent_alerts' or 'polymarket_edges'.

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. The description adds behavioral context by describing the output structure (category-bucketed example questions with tool + argument shape) and the list of categories. This goes beyond what annotations provide, giving the agent a clear picture of what to 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 relatively long but well-structured: it starts with example questions, then explains the output, then gives usage instructions. Every sentence serves a purpose. It could be slightly more concise by moving the category list to a more compact form, but overall it's 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?

There is no output schema, so the description must explain the return value. It does so by describing the category-bucketed examples and the tool shapes. It also covers usage with and without the topic parameter. For a simple tool with zero required parameters, this is fairly complete.

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

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

Schema coverage is 100% with a single optional 'topic' parameter that lists possible values. The description reinforces the behavior of omitting vs. providing a topic and gives example values, but it does not add significant new meaning beyond 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 uses specific verbs ('suggest questions', 'returns category-bucketed example questions') and clearly identifies this as the onboarding entry point for a new agent. It distinguishes itself from siblings like 'ask_pipeworx' and 'discover_tools' by positioning itself as the first tool to call when the agent doesn't know what Pipeworx can do.

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

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

The description explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It explains when to call with no arguments vs. with a topic. However, it does not explicitly state when NOT to use it (e.g., after the initial onboarding), which prevents a perfect score.

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

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

Adds ownership enforcement, soft-deactivation, and historical availability beyond annotations which only indicate idempotent and non-destructive.

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 action, 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?

Covers core behavior and side effects for a simple tool; lacks error case notes but acceptable given simplicity.

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

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

Single parameter 'id' is fully described in schema; description adds 'by id' but no new meaning beyond schema.

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

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

Explicit verb 'Cancel' and resource 'subscription', clearly distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

States ownership enforcement and deactivation behavior, but does not explicitly contrast with alternatives for permanent deletion.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral context beyond these annotations, such as the date range defaulting to the last 12 months and the distinction between searching by recipient name versus keywords. This helps the agent set correct expectations for query 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?

Three concise sentences deliver the core value proposition, parameter guidance, and return summary without any filler. The structure front-loads the purpose, then provides actionable usage details, making it easy for an agent to quickly grasp how to invoke the tool correctly.

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

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

Given the tool has 9 optional parameters and a detailed schema plus output schema, the description sufficiently covers the most important aspects: what is being searched, how to use recipient_name vs keywords, and date default behavior. It does not mention limit or pagination, but those are clearly defined in the schema. The description is adequately complete for a search tool of this 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?

The schema covers 100% of parameters, so the baseline is 3. The description adds meaningful semantic guidance that the schema alone does not convey: it clarifies that recipient_name should be used for a company's awarded contracts and that keywords should not contain company names. It also explains the cumulative effect of dates when the start/end dates are omitted. This goes beyond the basic parameter definitions.

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

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

The description clearly identifies the tool as a search engine for US federal procurement contracts and government contract awards, using a specific verb ('Search') and resource. It distinguishes itself from sibling tools by focusing on award transactions rather than broader spending trends or recipient profiles.

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

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

Provides practical usage guidance: explains that recipient_name is for company searches like 'Lockheed Martin' and that keywords should target award descriptions/topics, not contractor identity. Also clarifies date defaults for 'recent' questions. However, it does not explicitly state when not to use this tool or name alternative tools for different scenarios.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses that dates default to the last 12 months and that the response always states the window used. This adds useful behavioral context not captured by annotations.

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

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

The description is concise—two sentences—and front-loaded with the primary purpose. It avoids redundancy and every sentence adds meaningful information.

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

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

For a read-only retrieval tool with full schema coverage and an output schema, the description is complete: it explains the core purpose and the key behavior (date window), while the structured schemas cover parameters and return values.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds semantic value by explaining that start_date/end_date are optional and default to the last 12 months, which is not in the schema. This improves understanding of how the date parameters behave.

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: answering 'what federal contracts did [company] win recently?' and retrieving a contractor's federal contract awards. It uses a specific verb ('Answer/get') and resource ('contract awards') and differentiates from siblings like usa_award_search by focusing on the recipient profile.

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

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

The description provides clear usage context by giving an example query and noting that dates are optional with a default window. It does not explicitly name alternative tools, but the context implies when to use it—when you need a contractor's awards.

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, so the agent knows it is a safe, non-destructive, and idempotent read operation. The description adds value by specifying the return data structure (agency names, abbreviations, dollar amounts), which is helpful 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 a single, front-loaded sentence that efficiently communicates the purpose, parameters, and return values. No wasted words, and every element 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 presence of an output schema and comprehensive annotations, the description is adequate for a simple query tool. It explains the core functionality and return fields. However, it could be slightly enhanced by mentioning that it only covers US federal contracts or noting any limitations, but overall it is sufficiently complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions the parameters (fiscal year and quarter) and their defaults/optionality, but this does not add significant meaning beyond what the input schema already provides. The schema examples also illustrate usage.

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 breaks down US federal contract spending by agency, with parameters for fiscal year and optional quarter. It specifies the return values (agency names, abbreviations, dollar amounts), which is specific and distinguishes it from sibling tools like usa_spending_by_category.

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 on when to use the tool (querying spending by agency for a specific fiscal year and quarter) and includes default behavior (current year) and optional quarter. However, it does not explicitly exclude usage scenarios or contrast with similar sibling tools like usa_spending_by_category or usa_spending_trends.

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, etc., so the description's statement of returning spending totals adds minimal behavioral context beyond what the annotations provide. No contradictions.

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

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

The description is two sentences, front-loaded with the action and resource, and every word adds value. No wasted text.

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 presence of an output schema (mentioned in context) and clear parameter descriptions, the description is complete enough for an agent to understand the tool's function and when to invoke it.

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

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

The input schema has 100% coverage with descriptions for all parameters. The description adds no additional meaning beyond summarizing the categories available, so it meets the baseline without exceeding.

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: analyze federal spending by specific categories (industry, product/service, recipient, agency) and return spending totals. It distinguishes from siblings like usa_spending_by_agency by focusing on categories and grouping.

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

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

The description mentions using the tool for market research and identifying government contracting opportunities, providing usage context. However, it does not specify when not to use it or mention alternatives among sibling tools, leaving the agent to infer when this tool is preferred.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds context beyond these: it specifies that data is grouped by fiscal year/quarter/month and that it returns historical dollar amounts per period. It also clarifies the federal scope. There is no contradiction with annotations, but it doesn't disclose potential limitations like data lag or aggregation details.

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

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

The description is moderately sized but well-structured. It front-loads with natural-language example questions, then explains the tool's purpose, filters, grouping, and scope. All sentences contribute value, though the list of agencies adds some length. It is concise enough 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?

The description covers the core dimensions: purpose, usage context, filters, time grouping, federal scope, and an alternative tool for non-federal data. With an output schema present, it doesn't need to explain return values. It does not explicitly distinguish from sibling tools like usa_spending_by_agency or usa_spending_by_category, but the emphasis on trends implies the difference.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds practical meaning by listing example federal agencies (DHS, DOD, HHS, VA, DOE, NASA, State, Treasury) and clarifying that keywords and agency can be used together or separately. It also conveys that start_date defaults to a five-year window, which supports schema semantics.

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: tracking US federal contract/award spending over time, grouped by fiscal year, quarter, or month. It uses specific verbs like 'trended', 'growing', and 'history' and identifies the resource (USAspending.gov). It distinguishes from sibling tools by noting 'Federal only' and pointing to gov_contracts_search for state/county data.

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 with example questions and states it's for 'trend and budget-forecasting questions'. It gives a clear when-not-to-use directive: 'Federal only — for state & county award data use gov_contracts_search.' It also explains filter options (keywords or agency) and time grouping.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses important behavioral traits: the meaning of each verdict type, the critical caveat that 'could_not_verify' means the check did not happen and must not be treated as evidence, and the two different processing pipelines. This adds significant value beyond annotations.

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

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

The description is appropriately sized for the tool's complexity. It is front-loaded with trigger phrases and a concise definition, then methodically covers usage, processing, return values, and caveats. Every sentence earns its place without redundancy or fluff.

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

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

Given the tool's complexity (two pipelines, multiple verdict types, error semantics) and the absence of an output schema, the description is sufficiently complete. It explains return values, citations, the meaning of key verdicts, and the processing flow, leaving no obvious gaps for an agent to misuse the 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?

The input schema already provides 100% coverage for both parameters, including the meaning and default of tolerance_pct. The description does not add parameter-specific semantics beyond the schema, so 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 identifies the tool as a natural-language claim verification tool, with explicit trigger phrases and a specific verb-resource pair ('verify factual claims against authoritative sources'). It distinguishes itself from sibling tools by focusing on fact-checking and the two processing paths (SEC EDGAR for financial claims, grounded pipeline for everything else).

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,' providing direct usage context. It also outlines the automatic routing for financial vs. non-financial claims, and notes that it replaces multiple sequential calls, giving clear guidance on when to invoke this tool.

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