Abs Au

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context beyond annotations: the default model being free, the option to pass `_apiKey` to probe Anthropic with direct billing to the user, and the return structure. This helps the agent understand cost implications and external dependency, going beyond the basic 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?

Three sentences, each earning its place: first states the core function, second gives key configuration details (default model, API key, billing), third lists use cases. No filler, front-loaded with the action.

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

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

Despite lacking an output schema, the description compensates by specifying the return format: 'per-model {score, confidence, signals, raw_response} + a combined view'. It also covers default model and cost implications. It doesn't explain what 'signals' contains or potential rate limits, but for a read-only probe tool this is adequate.

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

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

Schema description coverage is 100% for all 4 parameters, so the baseline is 3. The description adds the default model behavior and the fact that `_apiKey` is passed through, but it does not materially add meaning beyond what the schema already explains for each parameter.

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

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

The description clearly states the tool's action ('Probe one or more LLMs for what they know') and resource ('business/brand/product/topic'), with specific output (visibility score 0-100 per model). It is specific enough to understand what it does, but it does not explicitly distinguish from sibling tools like scan_competitor_ai_presence, so it misses the 'distinguishes from siblings' criterion.

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

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

Provides clear use-case context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not mention when not to use this tool or direct to alternatives, but the stated use cases give the agent a clear sense of when to select it.

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

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

Annotations already cover readOnly, idempotent, openWorld, and non-destructive behavior. Beyond that, the description adds useful behavioral details: internal routing to many underlying tools, automatic argument filling, and stable pipeworx:// citation URIs in the output. It does not cover edge cases like latency or verification limits, but it offers meaningful extra context rather than just repeating annotations.

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

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

The description is long but well-structured: it starts with the main directive, lists supported domains, explains how the tool works, gives trigger phrases and examples, and then routes to alternatives. It could be trimmed slightly to remove redundant list overlaps, but the content remains purposeful and useful.

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 — routing across thousands of tools, no output schema, and potential confinement with web search — the description covers what it does, when to use it, what it returns, what kind of questions it answers, and when to choose siblings instead. No critical behavioral or usage information appears missing.

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

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

The input schema is fully described at 100% coverage: the one real parameter 'question' is clearly described, and all other aliases are documented as aliases. The description adds example queries and confirms natural-language input, but it does not materially enrich the parameter semantics beyond what the schema already says. This is an appropriate baseline for a fully-covered schema.

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

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

The description clearly states that ask_pipeworx is a routing-powered factual question-answering tool: it takes natural-language questions, routes them to the appropriate tool among thousands of verified sources, fills arguments, and returns structured answers with citations. It also distinguishes itself from web search and named sibling tools, making its role 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?

Explicit guidance is given: 'PREFER OVER WEB SEARCH' for factual/statistical/entity questions, 'START HERE for most questions', and concrete alternatives are named — ask_pipeworx_grounded for stricter grounding and deep_research for broad, open-ended research. This provides exactly the kind of when-to-use/when-not-to-use information an agent needs.

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

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

The annotations already cover read-only, idempotent, open-world behavior, and the description adds valuable beyond that: this is experimental, candidates can be enabled live, none is currently active, and there is no degraded fallback path. This prevents an agent from assuming 'beta' means incomplete or unsafe.

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

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

The description is front-loaded with the most important fact—it is a beta version of ask_pipeworx—and each sentence adds context: candidate state, matching behavior, and the absence of a degraded fallback. It is slightly dense with status details such as the retirement date, but on the whole every sentence contributes.

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-required-argument tool with full alias coverage and a clear sibling relationship, the description conveys what a caller needs: same arguments, same response shape, current behavior identical to ask_pipeworx, and no fallback gap. The only minor gap is that 'newest routing' is not deeply defined, but the comparison to the stable router gives sufficient 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 the required question parameter and all aliases documented. The description only says the arguments are the same as ask_pipeworx and adds no additional formatting, validation, or usage semantics, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as the beta variant of ask_pipeworx, an identical universal router covering the same 5,596 tools and returning the same response shape. It distinguishes the experimental edge from the stable ask_pipeworx, though it relies on the sibling's established meaning rather than stating the core action in a direct verb phrase.

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

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

It explicitly instructs the agent to use it exactly like ask_pipeworx when the newest routing is desired, and clarifies that its outputs are compared against the stable router to decide what merges. The absence of an active candidate is called out, so the agent knows when the behavior will be truly identical.

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 readOnly, idempotent, and non-destructive hints, but the description adds substantial behavioral detail beyond those: it explains how answers are constrained to tool output, the exact refusal reasons, the structured response shape, and the extra LLM call. There is no ambiguity about how the tool behaves or when it will refuse.

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

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

The description is dense but well-organized, with each sentence serving a distinct role: what the tool is, how it behaves, when to use it, and how it differs from the cheaper alternative. It could be trimmed slightly by shortening the full output-field list or the source-count detail, but it is still highly functional and front-loaded.

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

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

The tool is simple enough to call—only one required question parameter—but the description goes beyond that to document the output contract and refusal reasons, which is essential because no output schema is provided. It also gives cost, alternative-tool, and usage context. Nothing an agent needs to invoke it correctly is missing.

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

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

The input schema already documents all parameters at 100% coverage, including the question field and all its aliases. The description does not add parameter-level guidance, but it does not need to—the schema carries the full semantic burden. This matches the baseline expectation for high schema coverage.

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

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

The description opens with a distinct purpose: 'hallucination-resistant answer mode for high-stakes reads,' and immediately distinguishes itself from ask_pipeworx. It clearly states the mechanism—same routing and fetching as ask_pipeworx, but answer extraction is restricted to the tool result. This is a specific verb+resource statement, not a tautology.

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

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

The description explicitly states when to use the tool: whenever the answer will be quoted, cited, or acted on and the agent must not invent facts. It also names the alternative (ask_pipeworx), explains the cost trade-off, and recommends the lighter option for casual lookups. This gives the agent clear decision logic.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds extensive behavioral detail: resolver contract (market_match_confidence, alternatives), safety short-circuiting (low_confidence_match, market_closed_or_inactive), wide-spread tradeability flags, cancellation-rule parsing with ev_impact, news fallback fields, and parent-event extractor behavior. It even notes a recurring pure-rules loss from void settlements, going far beyond the annotation hints.

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

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

The description is very long, but every section earns its place by covering a distinct aspect: classifiers, fan-out examples, response shapes, resolver contract, parent events, news fallback, safety, and cancellation risk. It is well-front-loaded with the core purpose in the first sentence. While it could be condensed, the structured sections make it navigable and not redundant.

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

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

With no output schema, the description must explain return values and edge cases, and it does thoroughly. It details result.market, result.analysis, result.evidence, the resolver contract, parent_event, news fields, status codes, wide-spread handling, and resolution-rule risk. The tool is complex, and the description provides complete context for an agent to understand what to expect.

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

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

The input schema covers all three parameters (market, depth, include_raw) with descriptions and examples, giving 100% schema coverage. The description adds some context around how the market parameter is used (resolution, classification) and mentions depth indirectly via fan-out, but it does not materially improve on the schema's parameter meanings. Baseline 3 is appropriate when schema handles 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 opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It further clarifies the inputs (slug, URL, question text) and what the tool produces (evidence packet + market-vs-model comparison). This distinguishes it from siblings like polymarket_edges and deep_research by focusing on the full research workflow.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides rich context on inputs and fan-out behavior. However, it does not mention when not to use it or alternative tools (e.g., polymarket_edges for pure edge calculation), so it lacks explicit exclusions or 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?

Adds rich behavioral context beyond annotations: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. The annotation readOnlyHint=true is consistent with the non-mutating nature described. 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 long but every sentence adds utility, covering usage triggers, data sources, and output. It is front-loaded with examples and key emphasis. Slightly verbose but not wasteful for a multi-purpose tool.

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

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

Given the tool's complexity (2 entity types, multiple metrics, sorting), the description covers essential aspects: input constraints, data sources, sorting behavior, and output format. It also explains why this tool exists (replacing 8-15 sequential lookups). No output schema exists, so the description's return-value note is 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 already covers both parameters, but the description adds practical meaning: 'type' determines data source and 'values' expectations for companies vs drugs. Examples for tickers and drug names go beyond the schema's abstract descriptions. Slight gap: description does not map every schema detail, but adds enough value.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call. It provides specific verbs ('compare', 'rank') and distinguishes from sequential lookups, 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?

Explicitly instructs to always prefer this over sequential single-pack lookups when comparing entities. Provides example query patterns and explains what each entity type yields. This gives clear when-to-use guidance and names the alternative approach.

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, so the safety profile is known. The description adds valuable behavioral context about the ordered nature of dimensions and the significance of that order for constructing dataKey, which goes beyond the annotations.

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

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

The description is two sentences, front-loaded with the core function, then immediately provides usage context. No filler or redundant information.

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

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

For a simple tool with two parameters and no output schema, the description provides sufficient context: what it returns, how it relates to get_data, and the ordering requirement. Some detail on output structure could be added, but the essential information is present.

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 dataflowId and maxCodesPerDimension described in the schema. The description reinforces dataflowId's role but does not add significant meaning beyond the schema, 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 function: 'return its ordered dimensions and the valid codes for each' for one ABS dataflow. It also distinguishes itself from siblings by explicitly linking to get_data as a prerequisite, making its unique purpose evident.

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: 'Call this before get_data' and explains how to use the output to build a dataKey. It does not mention alternatives or when-not-to-use, but the directive is clear 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?

The description goes well beyond the readOnly/openWorld/idempotent annotations: it explains the parallel decomposition into facets, returns a findings packet with verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citations, explicit gaps[], contradictions[], semantic excerpting of large records, latency expectations, depth tiers, and the account/paid-plan constraint.

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

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

The description is dense and long but each sentence carries useful information about the tool's behavior, limits, output, and alternatives. The main downside is the structure: opening with account prerequisites rather than a tight statement of core purpose, and a single long paragraph that can be slightly hard to parse.

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

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

With no output schema, this description carries the full burden of explaining behavior; it does so extensively: what findings look like, what gaps[] are, what citations mean, when contradictions are returned, how depth differs, account limitations, expected latency, and when to prefer the sibling tool. Nothing critical is missing.

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

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

The input schema already documents both parameters thoroughly, including enum values for depth and the meaning of each tier. The description reiterates most of the same information, adding only latency expectations and some depth nuance; it does not materially extend the schema's parameter semantics.

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

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

The description clearly states the tool's specific verb and resource: grounded multi-source research across 1465 STRUCTURED data sources. It explicitly distinguishes itself from open-web search and from ask_pipeworx for single lookups, so an agent can immediately tell what this tool is for.

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 concrete when-to-use and when-not-to-use guidance: it is best for broad and multi-part structured-data questions, while single lookups should use ask_pipeworx, and breaking/current-news topics are better sent to ask_pipeworx. It also covers the unsigned-in fallback: use ask_pipeworx if not signed in.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to restate safety. It adds meaningful behavioral detail about the return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This explains the response structure and that no follow-up is needed.

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, each serving a purpose: purpose, use case, return behavior, and when to call. The domain list is long but informative, and there is no redundant or filler content. It's well-structured and front-loaded with the core verb.

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

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

Despite no output schema, the description fully covers the tool's purpose, input semantics, output characteristics, and usage context. It also integrates self-referential guidance ('Call this FIRST') which makes it self-contained. Annotations cover the safety profile, and the description fills in the rest.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters with clear descriptions and examples. The description's 'describing the data or task' aligns with the query parameter, and 'top-N' relates to the limit, but it doesn't add substantial new meaning beyond the schema's existing parameter documentation. 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: 'Find tools by describing the data or task.' It enumerates specific domains and explains it returns relevant tool schemas, which distinguishes it from sibling tools like get_data or deep_research that would retrieve data or research rather than tool metadata.

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 you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This positions it against alternatives and tells the agent to invoke it as an initial discovery step.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses important behavioral traits: it fans out across multiple sources, returns specific fields, includes URIs for filings, notes the USPTO patents source sunset and soft-fail behavior, and explains the GDELT→GNews fallback. This is rich contextual detail.

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

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

The description is long but densely packed with necessary information, especially given there is no output schema. It is front-loaded with usage examples and structured with semicolon-separated return fields, making it easy to scan. A slight reduction in phrasing would improve conciseness, but every sentence earns its place.

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

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

With no output schema, the description takes on the burden of explaining return values and edge cases. It lists the data sources (SEC, XBRL, USPTO, news, GLEIF), the exact fields returned (cik, recent_filings, fundamentals, patents, news, LEI), and failure behaviors (patents soft-fail). This makes the tool fully usable without further documentation.

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

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

Schema coverage is 100% and both parameters are well-described. The description adds examples (ticker 'AAPL', CIK '0000320193') and reinforces the requirement for zero-padded CIK, which provides practical clarity beyond the schema.

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

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

The description clearly states the tool creates a full cross-source profile of a US public company, with specific verbs like 'research' and 'brief me'. It distinguishes itself from siblings by explicitly preferring this tool over chaining single-pack SEC/XBRL/news lookups and referencing resolve_entity for name-based queries.

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

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

The description explicitly says to use this tool when a user asks for a holistic view and provides exclusions: names are not supported, and it directs users to resolve_entity first if only a name is available. This is clear when-to-use versus 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 signal destructive and idempotent behavior. The description adds context about what gets destroyed (a previously stored memory) and the rationale (clearing sensitive data), which goes beyond the raw annotations. It doesn't detail edge cases like missing keys, but the idempotent hint covers that.

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 concise sentences, front-loaded with the purpose, followed by usage guidance and complementary tools. Every sentence earns its place with no fluff or redundancy, making it efficient and easy to parse.

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

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

For a simple one-parameter destructive tool with strong annotations, the description provides purpose, usage triggers, and related tools. The lack of an output schema is acceptable for a delete operation, and the idempotent/destructive hints cover behavioral expectations, so the description is complete.

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

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

Schema coverage is 100% with the property 'key' described as 'Memory key to delete'. The description's 'by key' merely restates the schema. No additional semantic value is added beyond what the input schema already provides, 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 explicitly states 'Delete a previously stored memory by key', which is a specific verb (delete) and resource (memory by key). It clearly distinguishes from siblings like 'remember' (store) and 'recall' (retrieve), leaving no ambiguity about the tool's function.

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

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

The description provides explicit when-to-use scenarios: 'context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names complementary tools ('Pair with remember and recall'), giving clear guidance on placement in a workflow.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds behavioral context by stating it 'Fetches the page, extracts... and emits...' This clarifies the network operation and output format, which goes beyond the annotations. It doesn't disclose error handling or rate limits, but the safety profile is well covered.

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

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

The description is two well-structured sentences followed by a bulleted list of use cases. Every sentence contributes value, with the main purpose front-loaded and no redundant information. It is concise and easily scannable.

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

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

For a tool with 2 parameters and no output schema, the description covers the essential aspects: what it does, the process, output format, and typical use cases. It does not elaborate on edge cases or failure modes, but given the simplicity and existing annotations, the information is sufficiently complete for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, with both parameters (url and max_links) already documented clearly. The description does not add additional parameter-specific meaning beyond what the schema provides, aligning with the baseline of 3 for high schema coverage.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL' and details the process (fetches page, extracts title/description/key links, emits standard markdown). This is a specific verb+resource that distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on analysis rather than file generation.

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.' This gives clear context for when to use the tool, though it doesn't explicitly exclude alternatives or name sibling tools for comparison, leaving a minor gap.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds scale warning ('can be large') and return format, but it says 'Pass "all" to fetch everything' without clarifying that maxSeries (default 100) still caps decoded series. This creates a potential misunderstanding about whether 'all' bypasses the cap. No contradiction exists, but the disclosure is incomplete.

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

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

Four sentences, each earning its place: purpose, dataKey syntax, 'all' option, return format, and prerequisite. Front-loaded with the core action and no redundant words. Very efficient for the complexity it conveys.

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

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

The tool is complex due to dataKey construction, but the description covers the essential context: prerequisite dataflow_structure, return format (decoded series, dimension labels, time-indexed values), and scale warning. With no output schema, it gives enough return information. However, it omits the interaction between 'all' and maxSeries, which is a relevant caveat even though the schema documents maxSeries, so slight deduction from a perfect score.

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 5 parameters (100% coverage), so baseline is 3. The description significantly enhances dataKey semantics by explaining the SDMX dot-separated filter syntax, wildcards, '+'-joined codes, and the need to consult dataflow_structure for dimension order. This goes well beyond the schema's generic 'Dot-separated dimension filter' and is essential for correct invocation.

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 'Fetch observations from an ABS dataflow' – a specific verb ('fetch') plus resource ('observations') and scope ('ABS dataflow'). This clearly distinguishes it from sibling tools like dataflow_structure (which fetches dimension metadata) and list_dataflows (which lists available dataflows).

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 guidance: 'Fetch dataflow_structure first to learn the dimension order and valid codes,' which directly instructs the agent to use a prerequisite sibling tool. It also explains the role of dataKey and the 'all' option, making it clear when to use this tool for retrieving observations.

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

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

Annotations already cover read-only, idempotent, and open-world hints. The description adds useful behavioral context: returns IDs and descriptive names, supports case-insensitive substring matching, and provides concrete ID examples. It does not go into pagination or edge cases, but the annotations reduce the burden.

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 main purpose and followed by essential details. Every sentence adds value—no filler or redundancy.

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

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

For a simple list tool with no output schema, the description adequately covers the return concept (IDs + names) and how the output is used. It lacks explicit mention of pagination or limit behavior, but that is already in the schema. Given the tool's simplicity, this is sufficiently complete.

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

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

Schema coverage is 100% with well-documented parameters. The description adds only marginal value beyond the schema, such as example IDs and the notion of case-insensitive search, which the schema already states. 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 ('Browse or search') tied to a clear resource ('ABS datasets (dataflows)'). It distinguishes itself from siblings by explicitly stating that returned IDs are used with dataflow_structure and get_data, making the tool's role unambiguous.

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

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

The description clearly establishes when to use this tool: to discover dataflow IDs before querying with dataflow_structure or get_data. It gives context on the search filter but does not explicitly mention alternative listing tools or when not to use it, leaving a minor gap.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context: it returns only the caller's subscriptions and filters to active ones by default. It also discloses the exact return fields, which is valuable 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 two sentences, front-loaded with the core purpose, followed by return-field details and usage guidance. Every word earns its place with no redundancy.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers the return structure, default filtering, caller scope, and use cases. Critical information is present; nothing essential is missing.

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

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

The sole parameter include_inactive is fully documented in the schema with its meaning and default. The description adds no further parameter details, so with 100% schema coverage, 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 uses the specific verb 'List' with resource 'subscriptions', scoped to 'the caller's active subscriptions'. It also enumerates returned fields, clearly distinguishing it from sibling tools like subscribe/unsubscribe and other list 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 use cases: 'review what you're monitoring before adding more or to find an id to cancel'. This clearly frames when to use the tool, though it doesn't explicitly name alternatives or conditional 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 only indicate readOnlyHint=false, etc., so the description carries the burden. It discloses rate limiting (5/identifier/day), cost/free quota, the claim_token return behavior, and the team's daily digest process. No contradictions with annotations; all behavioral traits are clearly surfaced.

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?

Every sentence earns its place: purpose, use cases, exclusions, content guidance, claim_token workflow, operational facts, and rate limits. The description is information-dense and front-loaded; 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?

Given the tool's complexity (4 params, nested object, no output schema), the description fully covers the filing and recall lifecycle, limitations, and expectations. It explains the return behavior (claim_token) and the resolution process well enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful beyond-schema value by explaining how to use claim_token for follow-up reads, how to structure context (pack/tool/vertical), and what type values map to real-world scenarios. It does not redefine each parameter but enriches the workflow semantics.

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

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

Explicitly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates concrete use cases (bug, feature/data_gap, praise) and clearly distinguishes itself from sibling tools like ask_pipeworx by scoping to Pipeworx tools only. The verb+resource+scope is specific 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?

Provides explicit when-to-use guidance for each feedback type, a clear when-not-to-use exclusion (other MCP servers), and a fallback for identifying Pipeworx tools. Even covers content guidance ('don't paste the end-user's prompt') and the claim_token recall workflow for follow-up.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses useful behavioral details: 'Cached 5min-1h depending on window', 'derived from CF analytics-engine, no PII, just (pack, tool, count)'. These add transparency about data freshness, source, and privacy. 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 three sentences, front-loaded with the core purpose and then supported by use cases and context. The use case list is slightly extended but each item earns its place by explaining practical applications. No wasted words, though it could be slightly 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?

With no output schema, the description adequately explains what the tool returns: 'top tools, top packs, and total call volume' and 'just (pack, tool, count)'. It also covers caching behavior, making it complete for a simple single-parameter read-only tool. It doesn't need to explain return formats in more depth given the tool's simplicity.

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

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

The schema already provides 100% coverage for the 'window' parameter, including enum values and trade-off explanations. The description merely repeats the window options ('24h, 7d, or 30d') without adding new meaning, so it meets the baseline but adds no extra semantic value.

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: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume.' This specifies the verb (returns), resource (trending aggregates), and output (tools, packs, volume). It also distinguishes itself from sibling tools like discover_tools by focusing on real-time aggregate usage rather than tool discovery.

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

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

The description explicitly lists three use cases: discovering hot data sources, confirming a canonical tool, and aligning with agent needs. This provides strong contextual guidance. However, it does not mention when not to use this tool or explicitly reference alternative sibling tools, 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?

Even though annotations already mark the tool as read-only and idempotent, the description adds rich behavioral context beyond those tags. It discloses conditions like 'deviations >3pp emit a BUY/SELL EVERY LEG signal', 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it', and the semantic anchor threshold of 0.30 Jaccard similarity. It also specifies the partition placeholder filter behavior, giving the agent concrete decision-relevant 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 long, but every clause earns its place given the tool's complexity. It uses scannable labels like 'SEMANTIC ANCHOR', 'PARTITION FILTER', and 'FILL CHECK' to structure information. However, it is still a dense block of text; a few sentences could be compressed without losing meaning, so it stops short of a perfect score.

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

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

Despite lacking an output schema, the description completely specifies the return values in prose: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and 'partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade}'. It also explains the fill-check pricing behavior and edge cases like placeholder fraction limits. For a tool with two optional parameters and three modes, this is exceptionally complete.

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

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

Schema coverage is 100% with both parameters described, so the baseline is 3. The description adds significant meaning beyond the schema by explaining what each parameter does in context: 'event' walks child markets and computes partition_check, while 'topic' flattens markets and runs the comparator on the union. It also provides concrete examples like 'fed-decision-may-2026' and 'Strait of Hormuz traffic returns to normal', which enrich the schema's bare 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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from sibling tools like polymarket_fill_risk and polymarket_edges by naming the specific analysis techniques and modes (trending_scan, event, topic), making its unique 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 provides explicit mode selection guidance: 'Call with NO args for a trending_scan... pass event for... or topic for...' It also recommends 'event (recommended for a specific market)' and explains when cross-event mode is preferable ('catches ... patterns that single-event misses'). Finally, it directs users to a sibling tool for custom sizing: 'For custom sizing use polymarket_fill_risk.'

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 readOnlyHint/idempotentHint annotations, the description discloses caching ('Cached 1h at the KV level keyed on all knobs'), response structure (by_segment, _diagnostics), and caveats like the 24h-move warning and Fed signal unreliability. It also explains why certain gates exist (placeholder-slug filter, rare longshot triggers), providing deep 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 extremely long and dense, essentially a mini-spec for the tool, which makes it less concise than ideal. While it is structured with numbered segments and clear categories, many sentences cover algorithmic details (lognormal barrier, alpha values, gate relaxations) that could be obtained elsewhere, so not every sentence earns its place in a quick-reference 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?

The description thoroughly covers output structure (by_segment, fed_candidates, _diagnostics), parameter effects, edge case handling, and caching, leaving no obvious gaps. Since there is no output schema, the detailed description of response fields and diagnostics is essential and fully provided.

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 descriptions already cover 100% of parameters with defaults and examples, satisfying the baseline of 3. The description adds value by explaining how knobs interact (e.g., 'min_liquidity / max_spread_pp drop opportunities where edge isn't realizable') and the special behavior of min_partition_leg_kelly for basket trades, exceeding 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 opens with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' which clearly states the tool's verb, resource, and specific scope. It also identifies a targeted use case ('what should I bet on today') distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

It explicitly states the intended use case ('Built for what should I bet on today') and explains it avoids paging hundreds of markets, giving clear context. However, it does not name alternative tools or explicitly state when NOT to use it, so it stops short of a full when/when-not comparison.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint:false, so the safety profile is clear. The description adds substantial behavioral detail: snapshots only written on cache-miss (so gaps mean no scan), 60-day TTL bound, decay computed from daily closes net of default slippage, and a detailed breakdown of response fields. This goes far beyond annotation hints.

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

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

The description is long but well-structured with ARGS, RESPONSE, and LIMITS sections. Every sentence adds value—purpose, args, response schema, and limitations—without fluff. It is front-loaded with the core value proposition and then details.

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

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

Given no output schema, the description fully compensates by enumerating tracked[], expired[], and snapshot_dates[] fields, including what each contains (full time-series, first_seen, trend, decay_pp_per_day, lifespan_days). It also covers history depth limits and data generation nuances, making it complete for agent decision-making.

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

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

Schema coverage is 100% and both parameters have clear descriptions in the schema. The description repeats the defaults and limits (days default 14 max 30, window default '1wk') but does not add meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool's purpose: edge persistence and decay telemetry built from daily polymarket_edges snapshots. It contrasts with sibling tools like polymarket_edges by focusing on historical persistence ('how long has this edge existed and is it shrinking?'), making the differentiation 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 gives strong usage context by framing the core question and explaining why it matters ('a fresh wide edge and a 3-week-old wide edge are different trades'). It does not explicitly state when NOT to use the tool or name alternatives, but the contrast with polymarket_edges is implied through the snapshot-based telemetry 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 read-only and idempotent, and the description adds context about live CLOB depth checks, walk-the-ladder behavior, return verdicts, and the dominant loss mode (partial fill unhedged directional position). 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 dense single paragraph with many clauses and all-caps emphasis; while every sentence adds value, it is not concise and would benefit from structured bullets or mode-split sections.

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 enumerates return fields per mode (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; and basket-specific fields), plus per-leg details and risk indicators, making the tool fully self-describing for invocation.

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

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

Schema coverage is 100%, so baseline 3; the description enriches parameter semantics by explaining size_usd's dual interpretation (max spend vs target proceeds vs settlement notional) and the auto default for basket side, going beyond the schema's field-level 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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from sibling tools by naming polymarket_arbitrage and polymarket_edges as tools to precede, establishing unique 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?

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains the rationale (theoretical overround not capturable, partial basket fills create unhedged directional risk).

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 and idempotent behavior, but the description substantially enriches this with operational details: compatibility_warning trigger conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and the caveat that pre-mapped topics are not necessarily tradeable. This goes far beyond what annotations provide.

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

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

The description is longer than average, but every section adds necessary context for a complex cross-venue tool. It is well-structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose before going into details.

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 fully covers return semantics, including leg-by-leg prices, matched spread[], compatibility_warning, temporal_alignment, and skip counters. It also explains edge cases and failure modes comprehensively, making the tool's behavior predictable without needing additional documentation.

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

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

While the input schema documents all three parameters, the description adds crucial semantic meaning: how `topic` maps to shortcuts, how explicit tickers/slugs override the mapped side, and the relationship between parameters in the two modes. The schema examples are reinforced by the description's mode-based explanation.

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

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

The description clearly states the tool's function: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It further distinguishes itself from sibling tools by detailing two operational modes and the specific outcome it produces (leg-by-leg prices and matched spreads).

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 defines TWO MODES and explains when to use each: `topic` for pre-mapped shortcuts and explicit tickers/slugs for custom pairings. It provides strong contextual guidance around compatibility warnings and temporal alignment, though it does not explicitly name sibling alternatives for exclusion.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds important context beyond annotations, including the scoping mechanism ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the optional key omission for listing. It does not disclose error handling or return format, but for a simple lookup tool this is sufficient.

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

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

The description is two concise sentences, front-loaded with the primary action and a clear alternative. Every phrase adds value, including the scoping detail and the pairing guidance, without any 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 one optional parameter and strong annotations, the description covers all necessary context: purpose, usage examples, behavioral scope, and how it fits with sibling tools. The absence of an output schema is not an issue here since the return values are straightforward.

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

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

Schema coverage is 100% and already describes the key parameter as 'Memory key to retrieve (omit to list all keys)'. The description reinforces this by mentioning 'omit the key argument' and adds the context that values are 'previously saved via remember', but this is a minor addition beyond the schema.

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

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

The description clearly states the tool's function with specific verbs: 'Retrieve a value previously saved via remember, or list all saved keys'. It also distinguishes from sibling tools like remember and forget by explicitly mentioning them and the relationship.

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

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

It provides explicit usage context: 'Use to look up context the agent stored earlier' and gives examples of what to store. It also names alternatives and pairings: 'Pair with remember to save, forget to delete,' which helps the agent choose correctly.

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?

Annotation Contradiction: The description states 'Set mark_read:true to flag returned events read' which is a state-changing operation, while the annotations declare readOnlyHint: true. This directly contradicts the read-only annotation, making the behavioral disclosure unreliable.

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 no wasted words. Each sentence has a distinct role: purpose, return format, filtering, mark_read semantics, and polling/alternative access. It is front-loaded and highly efficient.

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

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

Given no output schema, the description compensates by explaining return contents (source, citation_uri, raw payload). It covers all parameters, side effects, polling suitability, and a direct HTTP alternative. For a read-oriented tool with one mutation flag, this is exceptionally complete.

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

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

Schema coverage is 100%, but the description adds valuable context beyond the schema by explaining the mark_read side effect ('so the next call only shows newer ones'), giving a concrete type example ('sec_8k'), and clarifying the 'since' filter compares against fired_at. This goes beyond what the property descriptions provide.

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

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

The description clearly states the tool pulls fired events from the subscription feed and returns the most recent alerts. It distinguishes itself from siblings like list_subscriptions by focusing on alerts rather than subscription management, with specific mention of return fields (source, citation_uri, payload).

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 (to retrieve recent alerts) and offers an alternative HTTP endpoint for scripts and dashboards. It does not explicitly compare to sibling tools like list_subscriptions or recall, but the purpose is evident enough to guide selection.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive; the description goes further with concrete behavior: parallel fan-out, GDELT→GNews fallback on rate limits/5xx, USPTO soft-fail after sunset, and structured grouped output with citation URIs. This 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 dense but every clause earns its place: user intents, source fan-out, fallback logic, parameter formats, return shape, and the alternative tool. No filler or redundant restatement of the title.

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

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

For a multi-source, fallback-rich tool with no output schema, the description fully covers inputs, source behavior, output shape (changes[] grouped by source, total_changes, citations), and the alternative static-profile path. There are no critical gaps.

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

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

Schema description coverage is 100% and already includes examples for `since` (ISO or relative) and `value` (ticker or CIK). The description repeats the `since` formats but adds no new parameter-level meaning beyond 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 the tool provides a change feed for a company over a time window, naming specific source types (SEC EDGAR, GDELT/GNews, USPTO). It differentiates itself from the sibling entity_profile by explicitly telling when to use that 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?

It gives example user queries, provides typical values for the `since` parameter, and explicitly contrasts with entity_profile ('Use entity_profile instead when you want the static profile'). This is strong when-to-use and alternative guidance.

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

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

Adds useful nuance beyond annotations: memory is 'scoped by your identifier,' authenticated users get persistent memory, and anonymous sessions retain for only 24 hours. This informs lifetime and visibility expectations. No contradiction with annotations (readOnly=false, idempotent=true) is present.

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

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

Three sentences, front-loaded with the primary purpose, followed by use cases and storage details. Every sentence contributes something important; no filler.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, when to use, persistence behavior, and sibling relationships. It is fully self-sufficient 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%, so baseline is 3, but the description reinforces key semantics by giving example keys and values and noting the key-value pair is 'scoped by your identifier,' which clarifies key uniqueness. This adds value beyond the bare schema.

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

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

The description opens with a specific action and resource: 'Save data the agent will need to reuse later' plus scope ('across this conversation or across sessions'). It clearly distinguishes from siblings by naming recall and forget as complements, so the agent knows exactly what this tool does relative to others.

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

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

Explicitly states when to use: 'Use when you discover something worth carrying forward...' and provides concrete examples (ticker, address, preference). It also says 'Pair with recall to retrieve later, forget to delete,' giving clear routing to 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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint=false), the description adds critical behavioral details: graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), internal cascading lookups, and explicit handling of unresolvable identifiers under 'unresolved'. This significantly enriches the agent's understanding of failure modes and output structure.

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 typical but well-structured: opens with concrete examples and usage directive, then organizes details per entity type, then adds fallback behavior. Every sentence adds value, though some technical details (e.g., 'via the GLEIF ISIN-to-LEI mapping') could be compressed. It earns its length through richness.

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

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

Given no output schema, the description compensates by explaining output structure (identifiers labelled by source, 'unresolved' field for failures) and coverage scope (EDGAR, GLEIF, OpenFIGI). It also notes the tool's efficiency ('replaces 2-3 manual lookups'). While a more formal output breakdown would be ideal, the description is sufficiently complete for an AI agent to understand what to expect.

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%, providing baseline 3. The description adds substantial value by elaborating on each type (company: cross-source identity spine with CIK/ticker/LEI/FIGI; drug: RxCUI with citation), acceptable input formats for value (ticker, CIK, ISIN, name), and specific examples like 'CH0038863350' resolving to legal entity. This goes well beyond the schema's brief descriptions.

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

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

The description clearly states the tool resolves names to canonical identifiers, with extensive examples ('What's the ticker for...', 'find the CIK for...') and explicit differentiation of supported types (company, drug). It distinguishes itself by explaining it replaces 2-3 manual lookups and provides identifiers needed by other tools, which is a specific verb+resource 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 explicitly advises 'Use FIRST whenever you have a name but need an ID' and gives concrete query examples. It implies when to use (name to ID mapping) and explains broad coverage. However, it does not explicitly state when NOT to use (e.g., if ID already known) or contrast with sibling tools like entity_profile or compare_entities, which could be clearer.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful context by stating it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density—details not present in annotations. No contradiction.

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

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

Four concise sentences, each serving a distinct purpose: main function, method of operation, use case, and return value. No fluff or redundancy; the key purpose is front-loaded.

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

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

For a tool without an output schema, it adequately describes the return format (ranked list with score, confidence, signal density) and internal behavior (use of ai_visibility_check). It also provides a clear usage scenario, making it sufficiently complete for an agent to select and invoke properly.

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 all parameters have meaningful descriptions (e.g., entities as subject vs competitors). The description does not add significant parameter-level meaning beyond the schema, only reiterating the multi-entity concept. Baseline of 3 is appropriate given the high schema coverage.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using a specific verb ('Compare') and resource ('AI visibility'). It distinguishes itself from sibling ai_visibility_check by emphasizing multi-entity comparison and ranking, and provides a concrete use case ('competitive AI-marketing audits').

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

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

The description gives a clear context for when to use it ('competitive AI-marketing audits') and provides an example query, implying it is for comparing your brand against competitors. However, it does not explicitly state when not to use it or mention alternative tools (e.g., compare_entities), so it lacks exclusion guidance.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses multi-source fan-out behavior, graceful degradation on partial failures ("sources_failed will list it if it times out, the rest still returns"), and a notable latency caveat ("bundlephobia's first measurement on a new version can take 5-30s"). This significantly enriches the annotation data without contradiction.

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

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

The description is dense but every sentence earns its place: purpose, usage, return value, ecosystem limits, and failure behavior. It is front-loaded with the core purpose, uses compact lists and parentheticals, and avoids filler. Appropriate length for a composite 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?

Despite lacking an output schema, the description thoroughly explains the return structure (summary block fields, per-advisory detail, links, alternatives) and behavioral edge cases (NPM-only, timeout handling). For a multi-source composite tool with partial failures and latency, this is a complete and actionable description.

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 'package' and 'version' already well-documented in the schema. The description adds minor context (e.g., scoped packages accepted, version defaults to latest) but does not materially enhance parameter meaning beyond what the schema states. Baseline 3 is appropriate as the schema carries the load.

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, composite purpose: "Composite 'should I add this npm package to my project' check in ONE call" and lists concrete data sources (deps.dev, bundlephobia) and checks (license, advisories, bundle size, etc.). It clearly distinguishes from siblings by emphasizing the compound nature and NPM scope, avoiding ambiguity with tools like scan_competitor_ai_presence.

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

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

Explicit usage triggers are given: "Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'". It also provides exclusions and alternatives: "NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly", directing agents to the correct tool for non-NPM packages.

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 cover safety (readOnly, openWorld, idempotent, non-destructive). The description adds critical behavior: 200K char cap with truncation flag, 500-char overlapping windows, BGE-base-en embeddings with cosine similarity, and output including character offsets and similarity scores. This is substantial disclosure beyond annotations.

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

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

Well-structured and front-loaded: purpose, usage, technical details. Every sentence adds information (offsets for verification, cap, model, pairing with another tool) without redundancy. Length is justified by the density of useful detail.

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

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

No output schema exists, but the description specifies return format (top-N passages, offsets, similarity scores) and limitations (truncation). It also provides a cross-tool workflow with ask_pipeworx_grounded. This makes the tool fully comprehensible and safely invocable.

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 at 100%, so baseline is 3. The description adds value by clarifying 'text' is already-fetched content with examples, enriching 'query' with natural-language examples, and noting the truncation behavior for 'text'. However, 'limit' semantics are fully in the schema, so this is solid but not exceptional.

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 'Semantic search INSIDE a fetched record' – a specific verb and resource. It distinguishes from siblings by focusing on already-pulled text and returning passages with offsets, clarifying it is not a whole-document search like ask_pipeworx.

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

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

It states 'Use when the record is too big to cram into the prompt' and gives a concrete alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This is explicit when-to-use and how it complements other 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?

With annotations present (write operation, open world, idempotent), the description adds valuable context: auth requirement, no persistence for anonymous/BYO, delivery channel details, phone verification, 10/day SMS cap, and webhook auto-disable on failures. This goes well beyond 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 dense but well-organized, with every sentence earning its place. It is front-loaded with purpose and uses specific examples without unnecessary fluff.

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

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

Despite the complexity (nested params, enum types, multiple delivery channels, no output schema), the description covers prerequisites, return value, supported types, delivery options, and operational limitations, making it fully self-contained 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% and descriptions are already rich. The tool description adds a few extra specifics (e.g., 'items:["5.02"] = officer change', phone verification URL, feed retrieval endpoint), providing marginal value over the schema.

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

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

The description clearly states the action ('Create a proactive monitoring subscription') and the resource ('live-data event stream'), names the return value, and distinguishes it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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 strong contextual guidance: it explains the prerequisite (OAuth account), differentiates subscription types, and mentions the always-on feed as a pull alternative. However, it doesn't explicitly say 'use this when you want X, use list_subscriptions to view' or mention 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 and idempotentHint, so the description adds meaningful behavioral context: returns category-bucketed example questions, includes tool+argument shape, and draws from live catalog. 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 a single dense paragraph, but every sentence delivers value. It is somewhat long but front-loaded with example queries and structured information about output.

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

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

The description fully explains what the tool returns, when to use it, and optional parameters. No output schema exists, but the description adequately covers return value structure in prose.

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 'topic' parameter is described in both schema and description with examples ('finance', 'pharma'), adding practical usage meaning beyond the bare schema.

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

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

The description clearly states the tool's purpose with specific verbs ('onboarding entry point') and resource ('Pipeworx' capabilities), and distinguishes it from siblings by positioning it as the FIRST tool to use when unfamiliar, while mentioning meta-tools like ask_pipeworx.

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

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

Provides explicit when-to-use guidance ('Use this FIRST when you do not yet know what Pipeworx can do for you') and describes optional topic filtering. While it doesn't explicitly contrast with discover_tools, the use case is well contextualized.

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=false and idempotentHint=true, but the description adds meaningful behavioral detail: it is a soft-delete ('deactivated, not deleted') and enforces ownership. This goes beyond the annotations and gives the agent a clear mental model of what happens on invocation.

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

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

Three short sentences, each with a purpose: the action, the ownership rule, and the side effect. No fluff or repetition. The structure is front-loaded with the primary action first.

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 operation with no output schema, the description is adequate. It covers the what, the constraint, and the persistence behavior. It doesn't mention the return value, but that's not critical for a cancel operation and the annotation set is strong. It also ties to recent_alerts for historical events, which completes the context.

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

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

The schema already documents 'id' as a subscription uuid returned by subscribe, which is high coverage. The description adds semantic constraint that the id must belong to the current user, which is not in the schema. This helps the agent understand a critical validation rule.

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 verb 'Cancel' and the resource 'subscription by id', which immediately distinguishes it from sibling tools like 'subscribe' and 'list_subscriptions'. It also adds scope ('Ownership is enforced') which clarifies the exact operation.

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

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

Provides clear context about when to use this tool (to cancel a subscription by id), including an important constraint (only own subscriptions) and a side-effect clue (deactivation not deletion). It doesn't explicitly name alternatives, but the implicit reference to 'recent_alerts' and the contrast with 'subscribe' makes the usage context 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 (readOnlyHint, idempotentHint, etc.), the description discloses critical behavioral nuances: that 'could_not_verify' means the check never happened and must not be treated as evidence, while 'unsupported' means no source covers it. It also reveals internal mechanics (SEC EDGAR fast path vs. grounded fallback) and explicitly warns callers about error handling.

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 serves a purpose: usage triggers, routing logic, return values, error semantics, and efficiency gains. It is front-loaded with user-phrase examples and maintains a clear structure despite its length.

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

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

With no output schema, the description fully explains what the tool returns: verdict categories, actual value with citation, and reasoning. It also covers edge cases (could_not_verify vs. unsupported) and integration notes (replaces multiple sequential calls), making it complete for an AI agent to invoke and interpret results reliably.

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 valuable context: it provides concrete example claims, explains how tolerance_pct overrides implied wording, and suggests values (1–2) for hallucination detection. This goes beyond the raw schema descriptions, though the schema itself is already quite clear.

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

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

The description uses a specific verb+resource: 'natural-language claim verification against authoritative sources.' It clearly distinguishes itself by listing natural-language triggers and stating it replaces 4-6 sequential calls, making its purpose unmistakable even among many 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?

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It further differentiates two routing paths (company-financial vs. any other factual claim), giving clear guidance on when this tool applies versus needing a fallback pipeline.

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