Bea Gov

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds important behavioral context: it makes external API calls when Anthropic is probed, and the BYO key implies direct cost to the user. It also discloses the return envelope, which is helpful given no output schema.

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

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

The description is three sentences, with the primary purpose front-loaded. Every sentence adds value: what it does, how the model selection works, what it returns, and use cases. No fluff or redundancy.

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

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

There is no output schema, so the description compensates by explicitly listing the per-model output structure (score, confidence, signals, raw_response) and the combined view. It also covers cost implications and typical use cases, making the tool's behavior fully understandable 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 coverage is 100%, so the parameters are fully described in the schema. The description adds minor value by stating the default model and clarifying the _apiKey use, but it does not significantly expand on the schema descriptions. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Probe') and clearly identifies the resource (LLMs) and the action (score visibility 0-100 per model). It distinguishes itself from sibling tools like ask_pipeworx by focusing on AI visibility auditing rather than asking questions.

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 for when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains how to choose models (default free workers-ai, optional anthropic with BYO key). It lacks explicit 'when not to use' or direct alternative comparisons, but the use cases are well stated.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. The description adds context by explaining it routes to thousands of tools, returns stable citation URIs, and is a 'one fast call' default. It does not disclose failure modes or rate limits, but with annotations covering safety, this is acceptable.

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

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

The description is lengthy but front-loaded with a strong directive ('PREFER OVER WEB SEARCH') and each sentence contributes distinct value, from domain lists to escalation paths. No redundancy, but it could be tighter; still earns a 4.

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 router with no output schema, the description explains the return value (structured answer with citations), usage triggers, and sibling alternatives. It lacks specifics on unmatched-question behavior, but overall it is adequate for a default entry point.

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 6 parameters (all aliases for 'question') and schema_description_coverage is 100% because each parameter includes a description. The description text itself does not add parameter semantics beyond examples already present in the schema, so baseline 3 applies.

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

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

The description clearly states what the tool does: routes questions to the appropriate one of 5,564 tools across 1,462 verified sources, fills arguments, and returns structured answers with pipeworx:// citation URIs. It explicitly distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research, positioning itself as the default entry point.

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

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

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' for a wide range of data types, and 'Use whenever the user asks...' with trigger phrases. It also states exclusions and alternatives: ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad questions, and clarifies that breaking-news is already covered.

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

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

Discloses the experimental nature, live candidate testing, and that it currently matches ask_pipeworx exactly. Adds context beyond annotations by clarifying 'Falls back to nothing — this IS a full working router', which tells the agent there is no fallback wrapper. No contradiction with readOnly/idempotent annotations.

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

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

Four sentences, each carrying distinct information: definition, current status, usage guidance, and fallback clarification. Slightly verbose but every sentence earns its place, with precise details like '5,564 tools' and the date of the last retirement.

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 covers what the tool is, how to use it, current behavioral state, and relationship to the stable version. It explicitly notes the same response shape, providing enough context for the agent to invoke it correctly.

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

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

Schema coverage is 100% with all six parameters being aliases of question, each fully described in the schema. The description merely mentions 'same arguments' without adding parameter-specific meaning, 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 identifies ask_pipeworx_beta as a 'Beta version of ask_pipeworx' and an 'identical universal router' with the same tools, arguments, and response shape. This distinguishes it from the stable sibling ask_pipeworx while clarifying it is a full working router with an experimental edge.

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 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router to decide merges. It also notes current state (no active candidate), so the agent knows it's safe to use now and when to prefer 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?

The description goes well beyond the annotations, detailing the exact return structure (answer, evidence, confidence, etc.) and explicit refusal reasons. It also discloses the extra LLM call cost and the strict extraction policy, providing comprehensive behavioral 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 succinct, front-loaded with the core purpose, then details output behavior and usage context. Each sentence adds value, with no wasted words, and the structure is clean.

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 covers the input (question), output (exact structure and refusal reasons), behavioral constraints (only uses tool result), and usage context. Despite no output schema, the description is complete and self-contained.

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

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

Schema coverage is 100% and the description does not add additional parameter semantics beyond what the schema already states (that 'question' accepts aliases). The baseline of 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 is a hallucination-resistant answer mode with specific routing and extraction behavior. It distinguishes itself from ask_pipeworx by noting the extra LLM call and the extraction-only-from-tool-result behavior, making the purpose specific and distinct.

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 given for when to use this tool ('Use whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'). It also describes the cost trade-off, providing clear scoping relative to alternatives.

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

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

Annotations declare read-only/idempotent/non-destructive, but the description significantly expands with fan-out behavior, response shape contracts, resolver confidence semantics, parent_event extraction, news fallback handling, and safety short-circuits like low_confidence_match and market_closed_or_inactive. This far exceeds annotation coverage.

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

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

The description is very long but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.), and every section adds operational value. It could be tightened, but the density is justified for a complex fan-out 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?

Without an output schema, the description fully specifies response shapes (market, analysis, evidence), resolver contract, parent_event, news fields, and safety statuses, covering edge cases like closed markets and wide spreads. It also addresses resolution-rule risk—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 descriptions are 100% complete, and the description adds practical semantics: it explains the market parameter accepts slug/URL/question, clarifies quick vs thorough depth, and details include_raw size tradeoffs (20KB vs 50-500KB). This enhances parameter 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 explicitly states it 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' and lists specific use cases and classifier categories. This clearly differentiates it from sibling tools like ask_pipeworx or 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?

Provides explicit 'Use for' scenarios ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and additional guidance on inspecting resolver contract and resolution-rule risk. It does not explicitly name exclusions or alternatives, but the context is unmistakable.

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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavior beyond that: SEC EDGAR/XBRL and FAERS data sources, correct handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. 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 dense but every sentence adds value: trigger phrases, preference rule, data sources, fiscal year handling, sort behavior, and return format. It is slightly long but still front-loaded with the core action and quickly 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?

The description fully equips an agent to select and invoke the tool: data sources, fiscal year nuances, sorting, output format, and efficiency gains. With no output schema, it compensates by explaining what the response contains (paired data + citation URIs).

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

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

Schema already describes both parameters with 100% coverage, so the baseline is 3. The description goes further by explaining what each type value actually retrieves (10-K metrics for companies, FAERS/trial counts for drugs) and reinforces that values accept tickers/CIKs or drug names, adding useful semantic context 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 explicitly states a side-by-side comparison of 2–5 companies or drugs in one parallel call, with clear trigger phrases like 'X vs Y' and 'which is bigger'. It also distinguishes itself from sequential single-pack lookups, making the tool's purpose unmistakable.

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

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

It gives explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also explains when to choose type='company' vs type='drug', and notes it replaces 8–15 sequential lookups, fully clarifying the intended usage context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the safety profile is established. The description adds the scope constraint 'all available' and the purpose of identifying datasets, providing some context beyond annotations, but it does not disclose potential behaviors like pagination or rate limits. For a zero-param list tool, this is 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?

A single sentence that front-loads the verb and resource, includes useful examples, and ends with the purpose. Every word earns its place with 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?

With zero parameters, an output schema present, and annotations covering safety, the description fully covers what an agent needs to know for this simple list catalog. It specifies the domain (BEA datasets) and the return intent, and there are no missing prerequisites or side effects to mention.

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

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

The tool has zero parameters, so the baseline of 4 applies. The schema is empty and the description adds no parameter-specific details, but none are needed.

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

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

The description uses a specific verb 'List' with a clear resource 'all available BEA datasets', provides concrete examples (NIPA, Regional, etc.), and states the downstream purpose 'to identify which dataset to query', which clearly distinguishes it from siblings like get_data or parameter_list.

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

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

The description implies this is a discovery step before querying data ('to identify which dataset to query'), giving clear context for when to use it. However, it does not explicitly name alternatives or state when not to use it, so it stops short of a full 5.

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

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

Even though annotations already indicate readOnly/openWorld/idempotent behavior, the description adds substantial context beyond them: account/plan requirements, parallel facet routing, findings-packet structure with gaps[] and contradictions[], citation_uri fetchability guarantees, semantic excerpting of large records, and latency expectations. There is no contradiction with 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 text is dense and nearly every sentence earns its place, covering success modes, failure modes, alternatives, and constraints. However, it is a single long unbroken paragraph and leads with sign-up/plan caveats rather than a crisp purpose statement, so it is not maximally front-loaded or structured.

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

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

With no output schema provided, the description compensates thoroughly by specifying the return shape: verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], and hop field. It also covers account gating, timing expectations, and known limitations, making it complete for a 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?

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by clarifying that multi-part natural-language questions are appropriate, that 'standard' is the default, and by explaining hop/gap-recovery/contradiction behavior tied to depth values. This exceeds the baseline but is not the strongest possible param-level elaboration.

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

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

The description clearly states the tool performs 'grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' in one call, explicitly distinguishing itself from 'open-web search' and from sibling tools like ask_pipeworx. It names a specific verb, resource, and scope, making its purpose unambiguous.

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

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

The description gives explicit when-to-use guidance ('Best for broad/multi-part questions over structured data'), when-not-to-use guidance ('For a single lookup use ask_pipeworx'), and even alternative routing for unsigned-in users and breaking/current-news topics. It also explains depth-level trade-offs, fully satisfying this dimension.

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

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

Annotations already cover read-only and idempotent behaviors. The description adds valuable behavioral details about the return format (top-N tools with schemas and examples, ready to call directly) and the recommended first-call strategy.

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 and logically organized, but the long list of domains adds length. Each sentence contributes value, though the domain enumeration could be more compact.

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

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

Even without an output schema, the description fully communicates what the tool returns (names, descriptions, full input schemas, curated examples) and when to use it. It leaves no significant gaps for an agent to invoke the tool confidently.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's 'top-N' and 'describing the data or task' align with existing schema descriptions for limit and query without adding meaningful new parameter-level insight.

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: finding/discovering tools by describing data or task, and lists specific domains. It distinguishes itself from siblings by explaining it returns full input schemas and should be called first.

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 contexts ('Use when you need to browse, search, look up, or discover') and advises calling this tool first when many tools are available. It stops short of naming specific alternatives or exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the bar is lower, but the description adds valuable behavioral context. It discloses that the tool 'fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF', that patents come from a 'USPTO PatentsView API sunset May 2025 — soft-fails until reactivated', and that news uses a 'GDELT→GNews fallback'. It also clarifies limits like 'up to 5' filings and 'LATEST 10-K', providing transparency about data freshness and coverage.

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

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

The description is dense but every sentence earns its place: it opens with concrete example queries, states the core function and preference, enumerates the fanned-out sources and returned fields, and ends with input constraints. Despite its length, it is front-loaded with purpose and structured with semicolons and lists, making it easy to parse. The minor redundancy with the schema is acceptable given the need for self-contained guidance.

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

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

There is no output schema, so the description must explain return values, and it does thoroughly: CIK + company_name, recent_filings with URIs, fundamentals (LATEST 10-K Revenues + NetIncomeLoss + Cash), patents, news via fallback, and LEI via GLEIF. It also covers limitations (patents soft-fail, names not supported, person/place coming soon) and usage constraints, making the tool's behavior and output fully understandable without additional context.

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

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

Schema description coverage is 100%, with both parameters already documented in detail, including examples ('AAPL', '0000320193') and the note about names not being supported. The description largely repeats this information ('Pass ticker "AAPL" or zero-padded CIK "0000320193" — names not supported...'). While it adds a few example user intents, it does not meaningfully enhance the parameter semantics beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool produces a 'full cross-source profile of a US public company in ONE parallel call', with a specific verb and resource. It also distinguishes itself from siblings by instructing to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic requests, making its 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?

The description gives explicit when-to-use guidance: 'when the user asks for a holistic view' and specifies the preferred alternative (single-pack lookups) to avoid. It also provides a critical exclusion: 'names not supported (use resolve_entity first if you only have a name)', directing the agent to the correct sibling tool. This is concrete and actionable.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true, so the description's 'Delete' aligns with those. It adds minor context about clearing sensitive data, but does not disclose additional behavioral details like irreversibility or behavior on missing keys, which are largely covered by the annotations.

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

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

The description is only two sentences, front-loaded with the core action and followed by usage guidance. Every sentence adds value with no redundancy or filler.

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

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

For a simple one-parameter mutation tool with annotations covering safety profile, the description fully covers what, when, and how it relates to sibling tools. No output schema exists, so return values are not needed. Complete and self-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 the single 'key' parameter, with a clear property description 'Memory key to delete.' The description's 'by key' reinforces but does not add new 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 states the action ('Delete a previously stored memory by key') with a specific verb and resource. It does not explicitly contrast with sibling tools, but the pairing with 'remember and recall' implicitly distinguishes the deletion purpose.

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

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

The description provides explicit when-to-use conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also advises pairing with 'remember and recall,' though it does not specify when not to use it or name alternative 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond these: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This explains the process and output form without contradicting the annotation safety profile.

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

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

The description is concise, front-loaded with the main action, then the method, then use cases. Each sentence contributes meaningful information without redundancy or filler, achieving high density in just three sentences.

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 two parameters and no output schema, the description fully covers the purpose, the process, and the expected output format. It also includes practical use cases. The annotations and schema handle safety and parameter details, so the description is complete enough for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, with both 'url' and 'max_links' already explained in the input schema. The description does not add parameter-level detail beyond what is in the schema, so the 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 function with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL'. It also distinguishes itself from sibling tools by focusing on llms.txt generation rather than general AI visibility scanning or entity research, making its purpose unambiguous.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context for when to use it. However, it does not explicitly name alternative tools or state when not to use it, which leaves some differentiation to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the description adds value by specifying the scope of data (NIPA, GDPbyIndustry) and the type of returned values (time series). No contradiction with annotations.

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

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

The description is a single sentence that front-loads the action and packs in relevant detail (datasets, data types, specific example) without any 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?

An output schema exists, so return value structure is covered. The description explains the kinds of data available and the dataset-specific nature, making it sufficient for tool selection. It does not cover pagination or error handling, but these are not essential given the annotations and output schema.

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

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

The schema description coverage is 0% for the single 'dataset' parameter. The description offers two examples (NIPA, GDPbyIndustry) and hints at dataset-specific parameters, but does not provide a comprehensive list or format details, leaving some ambiguity.

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 action ('Fetch actual BEA economic data') and the resource (specified dataset), with concrete examples like NIPA and GDPbyIndustry. It distinguishes from sibling tools such as dataset_list and parameter_list by focusing on data retrieval rather than metadata listing.

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 this tool: when actual BEA time series data (GDP, PCE, etc.) is needed. It implies the tool is for data queries but does not explicitly name alternatives or exclusions, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the agent knows it is a safe read. The description adds behavioral context by naming the return fields, scoping to the caller's subscriptions, and indicating the default is active-only. This goes beyond annotations without contradicting them.

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

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

The description is just two sentences, front-loaded with the action and return fields. Every sentence earns its place, with no filler or repetition.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers the return values, scoping, and default behavior. It also provides practical usage guidance, making it complete for an agent to invoke correctly.

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

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

The schema provides 100% coverage for the only parameter, include_inactive, with a clear description. The tool description's mention of 'active subscriptions' reinforces the default but adds no additional meaning beyond what the schema already states.

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 'List the caller's active subscriptions,' a specific verb+resource that clearly states the tool's function. It also distinguishes from siblings by describing use cases: reviewing active subscriptions before adding more or finding an id to cancel, which maps directly to subscribe/unsubscribe 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 explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This indicates when to use the tool, but it does not explicitly state when not to use it or name alternative tools, so it stops short of a 5.

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

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

Annotations already indicate a safe read-only, idempotent operation. The description goes further by stating the data is official government statistics (not analyst estimates), explaining the metric (value added contribution to GDP), noting the output is ranked per state, and flagging the limitation that birdwatching is not a separate line. This adds substantial context beyond the annotations with 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 dense but every sentence contributes: purpose, example uses, activity list, output format, an important caveat, and a pointer to an alternative tool. The key phrase 'MARKET SIZE' is front-loaded, making the tool's purpose immediately clear.

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

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

With no output schema and four optional parameters, the description fully covers what the tool returns (value added per state, ranked), the source (BEA SAOACTVA), how to invoke it for examples, and its limitations. It also differentiates from the sibling 'get_data' tool, making it self-contained for agent selection.

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

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

The input schema already covers 100% of parameters with clear descriptions, so the baseline is 3. The description adds value by explaining the meaning of 'value added' (contribution to GDP) and clarifying that states are ranked, which helps interpret the 'state' and 'activity' parameters. It also lists example activities that map to the schema, though the schema itself is more exhaustive.

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 names a specific verb ('MARKET SIZE'), a specific resource ('outdoor recreation activities in US dollars, by activity and state'), and cites the official BEA source. It distinguishes itself from sibling tools by explicitly directing other BEA data to 'get_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?

Provides concrete example queries ('how big is the hunting industry', 'fishing economy by state') and clear exclusions: warns not to use for birdwatching and points to 'get_data' for other BEA data. This gives the agent explicit when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint:false. The description adds that it returns parameter names, descriptions, data types, and requiredness, which is consistent with a safe read operation. It does not contradict annotations and offers useful context about the return content.

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?

A single, front-loaded sentence that conveys the purpose, scope, and output without wasted words. It is appropriately concise for the tool's simplicity.

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

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

Given the tool has one parameter, an output schema, and strong annotations, the description is complete. It explains what the tool does, what it returns, and the parameter's role. No further context is needed.

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 0%, so the description must compensate. It explains the 'dataset' parameter as a specific BEA dataset with an example ('NIPA'), giving meaning beyond the bare schema type string. However, it could have provided more detail on dataset name constraints or sources.

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

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

The description uses a specific verb ('List'), identifies the exact resource ('required and optional parameters for a specific BEA dataset'), and states the output fields. This clearly distinguishes it from sibling tools like dataset_list or parameter_values.

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

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

The description clearly states the tool operates on a specific dataset and provides an example, making it clear this is for retrieving parameter metadata. It does not explicitly mention alternatives, but the context implies when to use this over dataset_list or parameter_values.

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=true, idempotentHint=true, and destructiveHint=false, establishing a safe, non-destructive read operation. However, the description adds no additional behavioral context, such as what 'valid values' means, how the tool behaves, or any constraints on usage.

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 only one sentence and technically concise, but it is under-specified. It lacks any actionable detail and provides minimal value beyond the tool name and schema, making it more a placeholder than a concise, informative 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?

Although an output schema exists to explain return values, the description is still inadequate for a tool with two required but undocumented parameters. It does not explain the tool's purpose, usage context, or relationship to sibling tools, leaving the agent with insufficient information to select and invoke it correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden for parameter semantics. The description only says 'Valid values for a parameter,' which does not explain what 'dataset' and 'parameter' represent, their format, or how to construct valid inputs. This is a significant gap.

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 'Valid values for a parameter' is a noun phrase without an action verb, so it does not clearly state what the tool does (e.g., list, fetch, validate). It is nearly a restatement of the title 'Parameter Values' and provides no differentiation from sibling tools like 'parameter_values_filtered'.

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?

There is no guidance on when to use this tool versus alternatives such as 'parameter_values_filtered'. The description provides no context for when this tool is appropriate, no exclusions, and no mention of 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 already declare the tool as read-only and idempotent, so the description adds little behavioral context. The term 'filter-aware' is not explained, and no additional side effects, response characteristics, or edge cases are disclosed.

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 extremely short, which is concise, but it under-specifies the tool. A single vague phrase does not earn its place as it fails to convey necessary information, making it closer to under-specification than effective conciseness.

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

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

Given the 0% schema description coverage, two undocumented parameters, and an existing sibling tool with a similar name, the description is severely incomplete. It does not explain what makes the values 'filtered' or how this tool should be invoked 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 0%, and the description does not clarify the meaning or format of 'dataset' and 'target_parameter'. The tool name and description provide no semantic value for these parameters.

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

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

The description 'Filter-aware valid values' is vague and fails to state a clear verb or resource. It hints at returning valid values but does not explain what 'filter-aware' means or how this differs from the sibling 'parameter_values' tool.

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

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

No guidance is provided on when to use this tool instead of alternatives like 'parameter_values'. There is no mention of context, prerequisites, or exclusions.

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

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

Discloses important behaviors beyond annotations: the claim_token mechanism for tracking feedback, daily reading of digests, rate limit of 5 per identifier per day, and that it is free and doesn't count against quota. While annotations are minimal (all false hints), the description fully explains the tool's side effects and flow.

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

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

The description is long but every sentence earns its place—it covers purpose, usage boundaries, token flow, rate limits, and quota exclusions. It is front-loaded with the core purpose and uses clear paragraphs. Slightly dense but not wasteful; a 4 is appropriate given the tool's complexity.

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

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

Despite having no output schema, the description explains the claim_token return value and the process of checking resolution status. It also covers rate limiting, quota, and what content to include. For a feedback tool with nested context and no output schema, this description is richly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra semantic value by clarifying message content (don't paste user prompt, be specific), explaining claim_token usage for reading replies, and indicating that context is optional structured metadata. This goes beyond the schema's own 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 opens with a clear, specific verb ('Tell the Pipeworx team') and explicitly enumerates the feedback categories (broken, missing, needs to exist). It distinguishes this tool from siblings like ask_pipeworx by focusing on feedback rather than queries, and clarifies scope ('ONLY for tools served by this Pipeworx connection').

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: bug on wrong/stale data, feature/data_gap for missing capabilities, praise for positive experiences. It also states when NOT to use it (other MCP servers) and gives a fallback heuristic ('Not sure? Pipeworx tool names are the ones this connection lists'). This is exemplary usage differentiation.

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

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

Annotations declare readOnlyHint and idempotentHint, but the description adds substantial behavioral context: it is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached 5min-1h. This goes beyond the structured annotations.

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

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

The description is concise and well-structured, with the purpose stated upfront, followed by output details, use cases, and behavioral notes. Every sentence adds value and there is 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 the simple schema (one optional parameter), comprehensive annotations, and no output schema, the description adequately covers what the tool returns, the underlying data source, lack of PII, and caching behavior. It is complete for the tool's complexity.

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

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

The input schema fully documents the window parameter with enum values and semantics. The description mentions the window but does not add any additional meaning beyond the schema, so the baseline score of 3 applies.

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

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

The description clearly states the tool returns trending data on what other AI agents are calling on Pipeworx, including top tools, top packs, and total call volume. It distinguishes itself from siblings like ask_pipeworx by focusing on aggregated trending activity rather than answering individual questions.

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 an explicit 'Useful for' list with three concrete scenarios, guiding when to use the tool. It does not explicitly name alternatives or when not to use it, but the context is clear enough.

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

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

The description goes far beyond the annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false). It discloses sophisticated behavioral details: the 3pp threshold for partition signals, the ≥0.30 Jaccard similarity anchor, the >20% placeholder filter returning null, and the fill check against live CLOB depth. These are non-obvious behaviors an agent must know to interpret results correctly.

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?

Despite being long, every sentence contributes substantive information about tool behavior, filters, or response content. It is well-structured: core purpose first, then mode-by-mode details, then filters, then response format. There is no filler or tautology; the length is justified by the tool's complexity.

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

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

With no output schema, the description fully specifies the response structure: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and the partition_check object. It also covers edge cases (placeholder filtering, low similarity, thin legs) and references the fill-check pricing logic. This is a complete picture for safe invocation and interpretation.

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 high coverage (100%) with detailed descriptions for `event` and `topic`, including examples. The tool description reinforces these meanings by explaining what happens in each mode ('walks child markets', 'flattens markets, runs the comparator on the union'). It adds operational context beyond the schema's parameter syntax, but the schema itself already carries significant semantic weight, so this is not a 5.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (trending_scan, event, topic) and explicitly differentiates from siblings by naming polymarket_fill_risk for custom sizing. This is precise and unambiguous.

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

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

The description provides explicit usage guidance: 'Call with NO args for a `trending_scan`... pass `event`... or `topic`...' It recommends event mode for specific markets and topic mode for cross-event scanning, explains trade-offs, and names an alternative tool for custom sizing ('use polymarket_fill_risk'). It also includes a clear do-not-trade condition: 'realizable_edge_pp ≤ 0... do not trade 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 (readOnlyHint, idempotentHint, etc.), the description discloses rich behavioral details: caching behavior ("Cached 1h at the KV level keyed on all knobs"), the rareness of concentrated_longshot ("rare-by-design"), the 24h-move warning, the Fed note about unreliable signals, and diagnostics explaining why a segment may be empty. This far exceeds what annotations alone convey.

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

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

The description is long and dense, but it is organized into clear sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.) and front-loaded with the tool's core purpose. Every sentence carries useful information, though the sheer length makes it slightly overwhelming. It earns a 4 rather than 5 due to its 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?

With 9 parameters, no output schema, and high complexity, the description compensates thoroughly. It covers the response top-level structure, diagnostics, model family details, knob behavior, and caching. It even addresses edge cases like placeholder-slug filtering and the Fed note. This is complete for effective tool selection and invocation.

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

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

Although schema coverage is 100%, the description adds meaningful context: it groups knobs as "TRADEABLE-EDGE KNOBS", explains why min_partition_leg_kelly is needed (parent-level Kelly is always 0 for basket trades), and clarifies the relationship between min_kelly and partition opportunities. This significantly enhances understanding beyond the schema's per-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 opens with a specific verb+resource: "Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price." This clearly distinguishes it from siblings like polymarket_arbitrage or polymarket_fill_risk. It also states the intended use case ("what should I bet on today") and describes the three output segments, further disambiguating the tool's purpose.

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

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

The description provides clear context: it is built for agents to discover opportunities without paging through hundreds of markets, and it explains the tradeable-edge knobs. However, it does not explicitly name alternative tools or state when NOT to use this tool, so it falls short of a 5.

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

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

The description adds rich context beyond the readOnly/idempotent annotations: snapshot write triggers (cache-miss), TTL limits, gap semantics, and the sign convention of edge_pp_net. It also clarifies that decay is computed on daily closes, not intraday, which is critical for interpretation.

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 every sentence earns its place, covering the analytical purpose, parameters, response format, and limitations. The use of CAPITALIZED section labels (RESPONSE, LIMITS) aids navigation despite the 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?

With no output schema, the description fully compensates by documenting the response structure: tracked[], expired[], snapshot_dates[], and their sub-fields with meanings. It also covers edge cases like missing snapshot days and historical depth limits, making the tool's behavior predictable.

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

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

The input schema already covers both parameters with 100% description coverage, so the baseline is 3. The description largely restates defaults and window options without adding new semantic value. There is a minor inconsistency: description says 'max 30' while schema says 'clamp 2-30'.

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 'edge persistence and decay telemetry' built from daily polymarket_edges snapshots, which differentiates it from raw edge tools like polymarket_edges. It states the exact analytical question ('how long has this edge existed and is it shrinking?') and gives a specific trading context.

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 a clear use case by posing the question it answers and explaining why edge age matters, but it does not explicitly name alternative tools or provide when-not-to-use guidance. The snapshot-based framing implies distinctiveness, yet a direct contrast with polymarket_edges would strengthen 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?

The description goes beyond the readOnlyHint annotation by detailing the internal behavior: walks the order book ladder, computes top_of_book/vwap_fill_price/slippage_pp, returns various metrics, and warns about forced_directional_risk and partial fill conversion. This is rich behavioral context that helps the agent anticipate outcomes and risks.

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

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

The description is long but tightly structured: purpose first, then SINGLE-MARKET and BASKET sections, then usage warning. Every sentence adds essential information for correct tool invocation; there is no redundancy or filler. The use of tactical uppercase helps key requirements stand out.

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 modes, four parameters, no output schema), the description is remarkably complete. It enumerates return fields for both modes, explains verdict values (clean|degraded|cannot_fill), discloses defaults and clamping (size_usd 10–1,000,000), and provides risk context for partial fills and forced directional risk. The agent can confidently select and 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?

While the schema already has 100% coverage, the description adds significant meaning: it explains that `market` and `event` are mutually exclusive modes, `side` has mode-specific defaults and meanings (sell_yes in basket captures overround), and `size_usd` is interpreted differently (max spend vs target proceeds vs settlement notional). This is far beyond the schema's simple descriptions.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which is a specific verb+resource statement. It clearly distinguishes itself from siblings by explicitly naming polymarket_arbitrage and polymarket_edges and positioning itself as 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 guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial basket fills create unhedged positions) and differentiates single-market vs basket modes.

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/non-destructive, and the description adds substantial behavioral context: compatibility_warning triggers (two distinct cases), temporal_alignment semantics, and skipped_cross_type/subtype counters. It even warns that 'pre-mapped ≠ tradeable,' setting realistic expectations. 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 every sentence earns its place, using scannable labels like 'TWO MODES', 'RESPONSE', and 'SAFETY FIELDS' to structure dense information. It is front-loaded with the core purpose and then systematically covers modes, return fields, and warning conditions 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?

With no output schema, the description takes on the burden of explaining return values and does so thoroughly: leg-by-leg prices, top_spreads_pp, compatibility_warning cases, temporal_alignment, and skipped cross-type/subtype counters. It also covers edge cases and caveats, making this a complete specification for a complex cross-venue 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 all three parameters with enum lists and override semantics, but the description adds a richer model: topic is a pre-mapped shortcut while the explicit ticker and slug are custom overrides used together in mode 2. This clarifies parameter relationships beyond the bare schema, justifying a 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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly stating a specific comparative purpose and resource. It further details two distinct modes (topic shortcuts and explicit pairings), making the tool's scope and behavior unmistakable even among sibling tools.

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

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

The description explicitly separates 'TWO MODES' and gives guidance on when each is appropriate, including a strong caveat that most pre-mapped topics currently return compatibility_warning and are not tradeable. It explains when outputs are meaningful (equivalent bet shapes, aligned temporal periods) but does not explicitly name sibling tools as alternatives, so it stops short of a full guideline.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the agent knows this is a safe read operation. The description adds valuable behavior beyond annotations: the key omission behavior (list all keys) and the scoping to the agent's identifier (IP, hash, or account ID). This provides important context about privacy and data isolation without contradicting the annotations.

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

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

The description is three sentences, front-loaded with the action, and every sentence serves a purpose: action + list mode, usage rationale with examples, and scoping + integration with sibling tools. No fluff or redundancy.

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

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

This is a simple tool with one optional parameter and no output schema. The description covers the tool's purpose, usage context, scoping, and related tools, while annotations cover the safety profile. It is complete enough for an agent to know exactly when and how to invoke it, including the two modes of operation. The lack of an error-handling note is acceptable given the tool's simplicity and the presence of sibling tools for context.

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

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

The input schema already covers the single parameter fully with a description ('Memory key to retrieve (omit to list all keys)'), so schema coverage is 100%. The tool description repeats the same semantics and adds examples of keys (target ticker, address, notes), but this is usage context rather than new parameter-level meaning. Baseline 3 is appropriate since the schema does the heavy lifting and the description does not significantly extend parameter understanding.

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

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

The description clearly states the tool's dual function: retrieving a saved value by key or listing all keys when key is omitted. It specifically names the resource ('value previously saved via remember') and distinguishes itself from sibling tools (remember saves, forget deletes). The scoping to the agent's identifier further clarifies the exact domain.

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: to look up context the agent stored earlier, such as a target ticker, address, or research notes, without re-deriving it. It also names the complementary tools (remember to save, forget to delete), providing clear alternatives and a usage context.

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

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

Despite readOnlyHint annotation, the description discloses that mark_read:true mutates read state, explaining 'so the next call only shows newer ones', which is critical behavioral context. It also clarifies the return payload and the open-world nature of the feed.

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 purposeful sentences, front-loaded with the action and resource, no redundant words. Every sentence adds value: purpose, return info, filtering, state change, and alternative access.

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 return format, filtering, side effects, polling suitability, and an alternative endpoint. With no output schema, this is sufficient for a read-only/list tool with optional parameters. No major gaps.

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

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

Schema already covers all five parameters (100% coverage), so the baseline is 3. The description adds concrete examples (e.g., type 'sec_8k', ISO timestamp format) and clarifies mark_read semantics beyond the schema, earning a 4.

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

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

The description opens with a specific verb ('Pull'), names the resource ('fired events from your subscription feed'), and details the return payload (source, citation_uri, raw event payload), making the tool's function unambiguous. It also distinguishes from broad siblings like get_data by scoping to subscription feed events.

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 'Polls work fine' (when to use) and offers an alternative access method via URL for scripts/dashboards, giving clear guidance on when to use the tool versus other integration approaches.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the specific fan-out to SEC EDGAR, GDELT→GNews fallback on rate-limit/5xx, USPTO PatentsView sunset soft-fail, and the return shape with changes[], total_changes, and pipeworx:// citation URIs. This adds significant 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 front-loaded and dense with valuable detail, but the sentence about `since` formats duplicates the input schema's parameter description. Apart from that redundancy, it is appropriately sized for a multi-source 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?

Since there is no output schema, the description appropriately explains the return format, the sources and their fallback/sunset behavior, and the alternative tool. This makes it complete for an agent to select and invoke the tool correctly.

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

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

The input schema already has 100% coverage, including examples and guidance for `since` and `value`. The description mostly repeats the `since` format and adds source-fanout context, but does not materially extend parameter meaning 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 defines the tool as a change feed for a company over a time window, with multiple illustrative user intents. It also distinguishes itself from sibling tool entity_profile by explicitly stating when entity_profile should be used instead.

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

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

Usage is explicit through examples like 'What's new with X' and 'updates on Acme'. It gives an explicit alternative: 'Use entity_profile instead when you want the static profile...', and explains source fallback behavior so an agent can decide when to use this tool.

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

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

Annotations already signal idempotent and non-destructive write behavior. The description adds valuable context beyond that: key-value pairs are scoped by the agent's identifier, and retention differs by auth status (persistent for authenticated, 24 hours for anonymous). This clarifies durability and isolation without contradicting the annotations.

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

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

The description is four sentences, front-loaded with the primary action ('Save data the agent will need to reuse later'), and each subsequent sentence earns its place: usage trigger, storage model, persistence details, and sibling tool references. No redundant filler.

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

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

The description covers purpose, usage conditions, storage model, retention behavior, and related tools. It omits explicit mention of overwrite behavior and return confirmation, but the idempotentHint annotation mitigates the former, and the simple key-value nature makes the latter less critical. A note on successful save would make it 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%: both key and value have descriptive text and examples. The description adds only a minor note about 'scoped by your identifier,' which is already implied by the schema's key examples. Given the schema does the heavy lifting, a 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 the specific verb 'Save' and resource 'data the agent will need to reuse later,' making the core function immediately clear. It distinguishes from siblings by explicitly pairing with 'recall to retrieve later, forget to delete,' and provides concrete examples like 'resolved ticker, target address, user preference' that leave no ambiguity.

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: 'Use when you discover something worth carrying forward,' followed by tangible examples. It also contrasts with sibling tools by naming recall and forget, and adds context about persistence differences between authenticated and anonymous sessions, which helps an agent decide when relying on memory is safe.

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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: it explains internal cascading through multiple lookup endpoints, graceful degradation if GLEIF or OpenFIGI are unavailable, and how unresolved identifiers are explicitly reported under 'unresolved' rather than omitted. This goes well beyond what annotations convey and fully informs the agent of the tool's 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 longer than average but well-structured: it front-loads example queries and the core purpose, then organizes details by supported type. Every sentence adds value (e.g., graceful degradation, internal cascading). While some redundancy exists (e.g., repeated mention of 'use first'), the length is justified by the complexity of the entity resolution. Still, a slightly tighter edit could improve conciseness.

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

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

Given there is no output schema, the description fully explains what the tool returns for each type (identifiers, data sources, labeling, unresolved handling). It also clarifies graceful degradation behavior and internal cascade. This makes the description complete enough for an agent to understand inputs, behavior, and outputs without needing an output schema. The 'use first' guidance further contextualizes its role among 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 coverage is 100%, so baseline is 3. The description adds substantial meaning: for the 'company' type, it documents that it accepts ISIN in addition to ticker, CIK, or name, and explains the ISIN-to-LEI mapping. For 'drug', it details that it returns RxCUI, ingredient, brand, and a citation URL. These details are not present in the schema alone, significantly enriching parameter understanding.

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

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

The description opens with concrete example queries that illustrate the tool's purpose, then explicitly states it resolves 'user-spoken NAME to the canonical/official identifiers other tools require as input.' It distinguishes itself from sibling tools by advising 'Use FIRST whenever you have a name but need an ID,' positioning it as a prerequisite step before other tools that require these identifiers.

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 when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also details the supported types (company and drug) and what they resolve to, implicitly telling the agent when this tool is appropriate. It does not explicitly list when not to use, but the 'first' directive implies that if an ID is already available, this tool is unnecessary. The contrasting sibling tools further reinforce usage context.

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

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

Beyond readOnlyHint/idempotentHint annotations, the description reveals that it internally calls ai_visibility_check per entity, ranks results, and returns a list with score/confidence/signal density. This adds meaningful behavioral context, though it doesn't mention potential rate limits or API key handling 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 compact (3 sentences) and well-structured: main function first, then mechanism, then use case and return format. Every sentence adds value without redundancy.

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

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

For a tool with no output schema, the description adequately covers return format and primary behavior. It explains the orchestration logic and key details, though it could mention potential edge cases (e.g., invalid entity counts or model support) briefly, but these are already in the schema.

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

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

Schema description coverage is 100%, and the schema already explains each parameter (entities, models, _apiKey, context). The description does not add new meaning beyond what the schema provides, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It uses specific language about probing, ranking, and surfacing recognition, distinguishing it from sibling tools like ai_visibility_check (single-entity) and compare_entities (general comparison).

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

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

It provides a concrete use case ('competitive AI-marketing audits') and an example question, making the intended context clear. However, it does not explicitly say when NOT to use this tool or name alternative tools for single-entity checks, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it explains the tool fans out to two external services, that bundlephobia's first measurement can take 5-30s, and that partial failures degrade gracefully with sources_failed listing timeouts. This informs the agent of potential latency and partial-output behavior, which annotations do not provide. No contradiction with annotations.

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

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

The description is concise and well-structured: it opens with the core purpose, then provides usage guidance, return values, ecosystem scope, and failure behavior. Every sentence adds value and there is no wasted verbiage. The length is appropriate for a composite tool of this 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 the tool's complexity (composite of two external services, multiple output fields, no output schema), the description is remarkably complete. It specifies the exact return block with field names, per-advisory details, links, and alternative versions. It covers ecosystem limitations and partial failure behavior. Combined with the annotations and schema, the agent has everything needed to select and invoke the tool correctly.

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

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

Schema coverage is 100%, with both parameters well-described in the input schema: package (npm package name, scoped packages accepted) and version (specific version, defaults to latest when omitted). The description does not add additional parameter semantics beyond the schema, but it does not need to. Baseline 3 is appropriate because the schema carries the full burden.

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

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

The description clearly states what the tool does: a composite 'should I add this npm package' check that fans out to deps.dev and bundlephobia. It uses specific verbs and resources, and distinguishes itself from simpler alternatives by noting it's a one-call composite. The sibling tools are unrelated, so no ambiguity.

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 it: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', directing users to an alternative for non-NPM ecosystems. This is clear usage guidance with both 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?

Beyond the annotations (which already declare the tool non-destructive and read-only), the description reveals the algorithmic behavior: BGE-base-en embeddings with cosine similarity, 500-char overlapping windows, a 200K char cap with truncation flagged, and output details (character offsets and similarity scores). This is rich context that helps the agent predict results and edge cases.

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 thoughtfully front-loaded with the core purpose and usage, then adds technical details (embedding model, window size, cap) that materially affect behavior. Every sentence earns its place; there is no redundancy or fluff. The structure flows from high-level intent to implementation specifics.

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 the absence of an output schema, the description explains the return format (top-N passages with offsets and similarity scores), the input constraints (200K cap, truncation flag), and the tool's relationship to a sibling. For a straightforward three-parameter search tool, this is complete and lets the agent invoke it correctly.

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

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

Schema coverage is 100%, so the parameters are already well-documented in the schema. The description adds contextual examples for the query parameter and clarifies that text is 'already pulled' content, but it does not introduce new parameter-specific details beyond what the schema provides. A baseline of 3 is appropriate given the schema's thoroughness.

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

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

The description clearly states that search_within performs semantic search inside a fetched record, with a specific verb ('search') and resource ('record'). It distinguishes itself from sibling tools like ask_pipeworx_grounded by explicitly positioning search_within as the tool for searching inside already-fetched text when the record is too large for the prompt.

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 when-to-use guidance: 'Use when the record is too big to cram into the prompt.' It also names an alternative (ask_pipeworx_grounded) and explains how they complement each other ('fetch with the gateway, ground over the relevant passages instead of the whole document'), making the decision clear.

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

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

Beyond annotations, the description details auth requirements (OAuth, no anonymous/BYO persistence), SMS verification and cap, feed persistence, and the subscription ID return. 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?

Dense, well-organized description with front-loaded purpose. Each section (types, delivery) adds unique value without redundancy with the schema.

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 auth, return value, main types, and delivery; however, omits webhook delivery and two enum types from the description text, though schema fills these gaps.

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

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

Schema covers all parameters with good descriptions; the tool description adds context like items code semantics and phone verification requirements, which enhances understanding.

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

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

The description states a specific action: creating a proactive monitoring subscription to a live-data event stream, and notes it returns the subscription ID. This clearly distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides prerequisites (OAuth account), supported subscription types with parameter examples, and delivery channel details. It implicitly tells when to use this tool (to create monitoring) but doesn't explicitly name alternatives or exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description goes beyond annotations by explaining the return structure (category-bucketed questions), that it draws from a live catalog, and that it can be called with no arguments or a topic filter. 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 front-loaded with common user queries and structured with useful categories and examples. It is longer than necessary, with several redundant phrasings ('what can I ask', 'what is good for', 'what can you do'), but every substantive behavior is covered.

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 a simple optional-parameter schema, no output schema, and strong annotations, the description fully covers return format, usage modes, and relationship to meta-tools. It provides enough context for an agent to decide when and how 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?

Schema coverage is 100% and the schema already describes the optional 'topic' parameter and its possible values. The description's mention of examples like 'finance', 'pharma', and 'betting' adds no new information beyond the schema, so it stays at the 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 clearly identifies the tool as the onboarding entry point for an agent to learn what Pipeworx can answer. It uses specific verbs ('returns category-bucketed example questions') and distinguishes it from siblings by stating it is the 'first' stop and that it includes exact tool+argument shapes.

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

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

It gives explicit when-to-use guidance ('Use this FIRST when you do not yet know what Pipeworx can do') and explains how to call with or without a topic. However, it does not explicitly state when not to use it or name an alternative tool for similar discovery purposes (e.g., discover_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?

Beyond the annotations (idempotent, non-destructive), the description adds critical behavioral details: the row is deactivated, not deleted, and historical events remain available via recent_alerts. This gives a fuller picture of the tool's side effects and long-term impact.

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, each earning its place: the first states the core action and ownership rule, the second explains the deactivation behavior and historical data preservation. No fluff, well-structured.

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

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

For a single-parameter tool with no output schema, the description fully covers what happens on execution (deactivation, not deletion) and ties in related functionality (recent_alerts). It is sufficiently complete for an agent to understand the tool's effect.

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

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

The schema already fully describes the 'id' parameter as a subscription id returned by subscribe (100% coverage). The description's reference to 'by id' adds no new semantic detail beyond the schema, so it meets the baseline but doesn't go further.

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 action ('Cancel a subscription by id') and resource, distinguishing it from sibling tools like subscribe and list_subscriptions. It also adds specific scope (ownership enforcement) that makes the purpose unambiguous.

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

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

The description provides clear context: it is for canceling subscriptions, and ownership is enforced so only your own subscriptions can be canceled. It implies users should have a subscription id (likely from subscribe/list_subscriptions) but doesn't explicitly name alternatives or when-not-to-use cases, which keeps it just shy of a 5.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral context beyond these: the distinction between 'could_not_verify' (a failure, not evidence) and 'unsupported' (no source exists), the routing mechanics between structured and grounded pipelines, and the presence of verification_error details. This richer context helps the agent interpret results correctly, which is a significant transparency gain.

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 example phrasings and a clear purpose. Every sentence contributes value, covering routing, return values, and important caveats. However, it is slightly verbose and could be tightened without losing essential content, so it does not achieve a perfect 5.

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

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

With no output schema, the description carries the burden of explaining return values, which it does thoroughly (verdict types, value with citation, reasoning). It also covers parameter semantics through the schema, usage guidance, and behavioral nuances like error handling. Given the tool's complexity, the description is remarkably complete and leaves no critical gaps for the 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 description coverage is 100%, with both 'claim' and 'tolerance_pct' already given clear, detailed descriptions including examples and defaults. The tool description does not add meaning beyond what the schema provides—it mentions 'exact percent-delta math' but does not elaborate on parameter usage. Thus, 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 function: 'natural-language claim verification against authoritative sources.' It uses specific verbs like 'verify' and 'fact check' and describes the resource (claims) and the scope (company-financial vs. other factual claims). It also distinguishes itself from sibling research tools by noting it 'Replaces 4–6 sequential calls,' making its consolidated nature explicit.

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

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

The description explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing logic for different claim types (SEC EDGAR vs. grounded pipeline). However, it does not name alternative tools or provide explicit when-not-to-use guidance, so it falls short of a 5.

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