flights

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond that: the default free model, the BYO Anthropic key with direct billing to the user, and the per-model response structure. This transparency about cost and external API usage is valuable and not contradicted by annotations.

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

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

The description is three sentences with no fluff: the first sentence states the core action, the second covers model defaults and the API key requirement, and the third gives the return format and use cases. It is front-loaded and every word 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?

Despite lacking an output schema, the description explicitly enumerates the per-model return fields (score, confidence, signals, raw_response) and the combined view. It also covers model selection, cost, and use cases. A minor gap is the undefined nature of 'signals', but the overall mental model 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 description coverage is 100%, with clear descriptions for entity, models, _apiKey, and context. The description's mention of the default Workers AI model and the need for _apiKey to probe Anthropic essentially restates what the schema already says, adding no new parameter-level insight. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Probe one or more LLMs' and 'score visibility (0-100) per model'. This clearly distinguishes it from sibling tools like ask_pipeworx or compare_entities, which are general Q&A or comparison tools. It also states the output format immediately.

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

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

The description provides clear usage context by listing 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly name alternatives like scan_competitor_ai_presence or say when not to use this tool, but the use cases are specific 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, open-world, idempotent, and non-destructive behavior. The description adds meaningful context: it routes to many tools, fills arguments, returns citations, works on every tier, and is a single fast call. This goes beyond the annotations without contradicting them.

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

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

The description is longer than many, but every sentence carries information: preference, scope, examples, alternatives, and edge-case behavior. It is front-loaded with the most critical directive ('PREFER OVER WEB SEARCH') and organized logically. While not as terse as possible, it earns its length.

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

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

For a complex, high-level tool with no output schema, the description is remarkably complete. It covers purpose, data source scale, output format (citations), default status, alternative tools, and example queries. The absence of an output schema is compensated by the description's clear explanation of what the agent can 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%, so the baseline is 3. The description adds value by providing example questions that illustrate the expected natural-language format, such as 'current US unemployment rate' and 'Apple's latest 10-K'. These examples help the agent formulate effective queries beyond the schema's terse description.

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

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

The description clearly states the tool's purpose: it routes questions to 5,529 tools across 1,455 verified sources and returns structured answers with citations. It provides concrete examples and explicitly contrasts with siblings like ask_pipeworx_grounded and deep_research, making its unique 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?

Usage guidance is explicit and actionable: it says 'PREFER OVER WEB SEARCH', identifies it as the default entry point, and gives specific conditions for stepping up to more specialized tools. It also notes when not to use it (e.g., breaking-news scenarios where it still routes appropriately), which is excellent guidance.

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

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

Annotations already declare readOnly=true, idempotent=true, destructive=false, so the bar is lower. The description adds valuable context about the experimental edge, candidate routing improvements, and that behavior currently matches stable exactly. It discloses the testing/comparison process and confirms it's a fully working router. 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?

Three sentences with all critical info front-loaded: identity, current state, usage, and caveats. The 'falls back to nothing' phrase is clarified immediately. No wasted words.

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

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

The tool is a beta variant of a known sibling, so referencing ask_pipeworx for arguments and response shape is sufficient. It covers current behavior, experimental nature, and usage context. The ambiguous 'falls back to nothing' is explained. Without an output schema, the 'same response shape' note helps complete the picture.

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

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

The input schema has 100% description coverage for all six parameters (question plus aliases), so the baseline is 3. The description only says 'same arguments' without adding further detail, which is acceptable given the schema already explains 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 explicitly states it is a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It clearly distinguishes itself from the stable ask_pipeworx by emphasizing experimental routing improvements, so the purpose is unambiguous.

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

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

It explicitly instructs to use exactly like ask_pipeworx when wanting the newest routing, and mentions results are compared against stable router. It doesn't explicitly name ask_pipeworx as the alternative for stable use, but the contrast is clear. Effective guidance without formal exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial behavioral context beyond these: it reveals the internal routing, the extraction policy (uses ONLY the tool result), the cost implication (one extra LLM call), the structured return shape including refusal_reason, and a full list of refusal reasons. This thoroughly discloses what the agent should expect.

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

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

The description is dense but every sentence earns its place. It front-loads the core differentiator (hallucination-resistant), then explains mechanism, return shape, usage, and cost tradeoff in a logical flow. 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?

This is a complex tool with no output schema, yet the description fully documents the return shape, success/refusal behavior, and failure modes (data_truncated, no_tool_match, etc.). It also explains the tradeoff versus the sibling tool, making it complete for an agent to decide and safely invoke.

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

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

Schema coverage is 100% and the schema already describes each alias and the question parameter in natural language. The description adds no further semantic detail about the parameters themselves, which is acceptable given the schema's completeness. Thus baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes itself from ask_pipeworx by emphasizing grounded extraction and explicit refusal behavior, and the sibling list includes ask_pipeworx, 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?

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also names the alternative: 'prefer ask_pipeworx for casual lookups,' and notes the extra LLM call cost tradeoff. This is textbook usage guidance.

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

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

Annotations already communicate readOnly, openWorld, idempotent, and non-destructive behavior, but the description goes far beyond by disclosing resolver contracts (market_match_score, alternatives[], suggestions[]), safety short-circuiting (status:'low_confidence_match'), handling of closed/dead markets, wide-spread illiquidity flags, and resolution-rule cancellation policies. This is rich behavioral context that no annotation could convey, and it does not contradict any annotation.

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

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

The description is long but extremely well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded purpose. Every sentence appears to add substantive detail relevant to successful use, making the length appropriate for a complex tool, though it could arguably be trimmed for raw conciseness.

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

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

With no output schema, the description must fully explain return values, and it does: result.market, result.analysis, result.evidence, resolver contract fields, parent_event, news fallback fields, and status conditions. It also covers resolution-rule risk and parameter tradeoffs. For a tool of this complexity with no structured output schema, the description is exceptionally complete.

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

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

The input schema covers all three parameters (market, depth, include_raw) with descriptions, so baseline is 3. The description adds context on fan-out behavior and typical usage examples, but does not materially expand parameter semantics beyond the schema—e.g., it never directly explains the 'depth' enum values or the 'include_raw' size tradeoffs beyond what the schema already states.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states the tool resolves, classifies, fans out, and returns an evidence packet plus market-vs-model comparison, distinguishing it from sibling tools focused on edges, arbitrage, or general search.

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

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

The text explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', which gives clear context for when to invoke it. However, it does not explicitly name alternatives or state when NOT to use it, though the purpose itself separates it from related Polymarket 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?

The description adds substantial behavioral detail beyond the annotations: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, sorting by primary metric, and the return format (paired data + citation URIs). It also discloses that results are sorted so 'largest' reads off the top, which helps the agent set expectations.

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 the one-sentence ideal, but every clause adds functional information (triggers, data sources, sorting, citations). It is front-loaded with the most critical trigger examples and preference instruction, then dives into specifics. The density justifies the length, though it could be slightly tightened.

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

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

With no output schema, the description compensates by describing the return format (paired data + citation URIs) and sorting behavior. It also covers data source specifics and fiscal year handling. Combined with read-only and idempotent annotations, the agent has a complete picture of what to expect and how to use the tool.

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

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

While the schema already describes both parameters (coverage 100%), the description enriches their semantics by explaining what each 'type' actually pulls (e.g., company -> 10-K revenue, drug -> FAERS counts) and gives examples for 'values'. This goes beyond the bare enum and array descriptions, adding meaningful context for parameter selection.

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

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

The description opens with concrete trigger phrases and a specific verb+resource: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It clearly distinguishes itself from sibling tools like entity_profile or resolve_entity by emphasizing the multi-entity comparison scope and the efficiency gain over sequential lookups.

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: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also enumerates the exact user expressions that should invoke this tool ('X vs Y', 'which is bigger', 'rank these companies') and scopes the tool to 2–5 entities, which tells the agent when to choose it over 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?

The description richly discloses behavioral traits beyond the annotations: latency (15-60s, thorough up to ~90s), return structure (findings packet with verbatim evidence, confidence, source, fetched_at, citations), gap handling (explicit gaps[], never invented), contradiction scanning, semantic excerpting, and citation_uri fetchability guarantees. The annotations only state readOnly/idempotent/destructive hints, so the description adds substantial value. No contradiction with annotations.

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

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

The description is long but dense; each sentence contributes meaningful context, from account requirements and core purpose to use cases, depth mechanics, citation guarantees, excerpting, and latency. It is front-loaded with the account note and a clear summary of what the tool does. While tightness could be slightly improved, the length is justified by the tool's complexity.

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

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

With no output schema, the description fully compensates by explaining return values (findings packet, gaps[], contradictions[], hop field, citation_uri), edge cases (never invented, semantically excerpted passages), and performance expectations. For a complex research tool, every aspect needed for correct invocation and interpretation is covered.

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

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

Both parameters are fully described in the schema (100% coverage), and the description mostly reiterates what the schema already says about depth levels and the question field. It does add context about the paid plan for thorough and latency expectations, but these are marginal beyond the schema. The 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's purpose with a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources...' It explicitly distinguishes itself from open-web search and from sibling tools like ask_pipeworx. The decomposition and parallel routing behavior further nails down what makes this tool unique.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and when to use alternatives such as 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also mentions account prerequisites and the alternative for unsigned users, making tool selection unambiguous.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds behavioral detail beyond that: it specifies the return format ('names, descriptions, and full input schemas with curated examples') and the efficiency property ('no second schema lookup needed'). It doesn't mention rate limits or auth, but for a read-only discovery tool this is sufficient given the annotation coverage.

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

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

The description is three sentences, front-loaded with the core action ('Find tools...'). The domain list is long but serves as useful query examples and occupies less than half the text. The 'Call this FIRST' advice is strategic and earns its place. No redundant or filler content.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so explicitly ('top-N most relevant tools with names, descriptions, and full input schemas'). It also covers the tool's scope with the domain list and mentions the 'ready to call directly' benefit. Annotations cover safety, so the description is complete for a discovery tool.

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

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

The input schema has 100% coverage with descriptions for every parameter, including aliases (q, task, search, description) and limit. The description's phrase 'describing the data or task' aligns with the query parameter, and 'top-N' clarifies limit, but it doesn't extend significantly beyond what 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 clearly states the tool's function: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from siblings by noting it returns the tool set itself ('Call this FIRST... to see the option set, not just one answer'), which differentiates it from tools that perform the actual tasks.

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 when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It implies when not to use it ('not just one answer') but doesn't name an alternative tool directly, slightly reducing the clarity of 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds meaningful behavioral context beyond these hints: it reveals the patent data source sunset ('PatentsView API sunset May 2025 — soft-fails until reactivated'), the news fallback chain ('GDELT→GNews fallback'), the parallel fan-out nature, and the sorted/filtered fundamentals ('LATEST 10-K Revenues + NetIncomeLoss + Cash, sorted period_end DESC'). It does not contradict annotations and adds value, though it could have mentioned rate limits or error behavior.

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

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

The description is dense but efficient, front-loaded with example queries and ending with parameter restrictions. Every sentence carries meaningful information. It is slightly long and run-on, but for a complex tool with no output schema, the length is justified. A structured bullet list would improve scannability, but the current format is acceptable grading.

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

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

The tool has no output schema, so the description carries the full burden of explaining return values. It thoroughly enumerates the returned fields (cik, company_name, recent_filings with URIs and count, fundamentals with specific metrics and sorting, patents with source caveat, news with fallback, LEI). It also covers input constraints and failure modes (names unsupported, patent soft-fail). For a tool of this complexity, the description is remarkably complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters in detail, including the 'names not supported' caveat and the resolve_entity fallback. The description adds only minor value by giving concrete examples ('AAPL' and '0000320193') and reinforcing the zero-padded CIK requirement. This is a baseline 3 since the schema does most of the work.

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+scope: 'full cross-source profile of a US public company in ONE parallel call.' It provides numerous concrete example queries and explicitly distinguishes itself from single-pack lookups, stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' This clearly differentiates it from sibling tools like resolve_entity or deep_research.

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

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

Usage guidance is explicit and actionable. It states when to use the tool ('when the user asks for a holistic view'), provides a preference directive ('ALWAYS PREFER'), and gives an exclusion with an alternative ('names not supported (use resolve_entity first if you only have a name)'). This is the textbook example of clear usage guidelines.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to repeat them. It adds no behavioral context beyond the annotations—no mention of irreversibility, failure behavior, or key-not-found handling. It only adds usage guidance, which belongs to a different dimension. 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?

Two sentences, action is front-loaded, no filler. Every phrase earns its place: the delete operation, the 'by key' qualifier, and the usage trigger conditions plus sibling tools.

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 (one required parameter, no output schema, no nested objects). The description covers what the tool does, when to use it, and how it relates to siblings. Annotations cover safety implications. Nothing essential is missing for this tool's complexity.

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

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

Schema coverage is 100%, and the single parameter 'key' is described as 'Memory key to delete.' The description reinforces 'by key' but adds no new semantic detail beyond the schema. Baseline 3 applies because the schema carries the full 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 begins with a specific verb and resource: 'Delete a previously stored memory by key.' This is unambiguous and distinguishes it from sibling tools like remember and recall, which store and retrieve memories respectively.

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 conditions are given: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also names complementary tools: 'Pair with remember and recall,' which signals when to use those alternatives and this tool's role in the 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context: it fetches the page, extracts specific elements, and returns a single text blob in standard llms.txt markdown. This goes beyond the annotations without contradicting them.

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

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

The description is compact: three sentences that lead with the core purpose, then a brief process summary, then specific use cases. Every sentence adds value, with no redundancy or filler.

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

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

For a two-parameter tool with no output schema, the description is complete: it explains the tool's purpose, process, output format, and likely use cases. The annotations cover safety, and the description covers behavior and output, leaving no significant gaps for an agent to select and invoke the tool correctly.

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

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

The input schema has 100% parameter coverage with clear descriptions for both 'url' and 'max_links'. The description adds context about the URL (foreshadows fetching and extracting), but doesn't elaborate on 'max_links' beyond what the schema already states. Baseline is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's verb ('Generate'), the specific resource ('llms.txt file for any URL'), and the concrete actions (fetch page, extract title/description/key links, emit markdown). This 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 ('Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving context on when to use the tool. It doesn't explicitly mention alternatives or when not to use it, but the guidance 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?

Annotations already cover safety (readOnlyHint, openWorldHint, idempotentHint, destructiveHint: false). The description adds meaningful behavioral context: 'No key required' discloses authentication needs, and 'plus its LIVE position if it is currently transmitting' clarifies conditional data availability. This goes beyond annotations without contradicting them.

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

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

The description is compact and front-loaded: identification, return contents, auth requirement, usage examples, and alternative tool in just five short sentences. Every sentence earns its place with no redundancy or filler.

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

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

For a simple one-parameter tool with an output schema, the description fully covers purpose, parameter semantics, usage examples, authentication, and alternatives. The presence of an output schema means return values are already defined, so no additional explanation is needed. Complete and self-contained.

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

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

Schema coverage is 100% for the single parameter, with format, case-insensitivity, and examples already given. The description reiterates the ICAO24 hex format but adds little beyond the schema, 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 is highly specific: 'Look up ONE aircraft by ICAO24 transponder hex' clearly identifies the verb, resource, and scope. It distinguishes itself from siblings like get_flights_in_area by emphasizing single-aircraft lookup, and explicitly mentions a sibling alternative. It also enumerates return contents (registry details, live position), leaving no ambiguity.

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

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

The description gives explicit when-to-use guidance: 'Use for "what is aircraft <hex>", "who operates <hex>", "where is <hex> now"'. It also provides a clear exclusion: 'If you only have a flight number/callsign, use get_flight_route instead.' This is exactly the kind of direct, actionable usage guidance expected.

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, but the description adds critical behavioral context: 'no key required', 'nearest first', the specific return fields, and the significant caveat that historical windows require OpenSky credentials and self-hosting ('OpenSky is unreachable from cloud egress'). This goes well beyond the annotations.

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

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

The description is compact and front-loaded: the first sentence states the core purpose, the second provides usage and output details, and the third resolves ambiguity about live vs. scheduled data. The historical caveat is parenthetical to avoid distraction. 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 5 parameters, a detailed schema, rich annotations, and an output schema, the description is complete. It covers use cases, limitations, and technical requirements, leaving no significant gaps 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 coverage is 100%, so baseline is 3, but the description adds meaning by giving ICAO examples, clarifying that results are 'nearest first', and explaining the begin/end historical limitation in context. It reinforces and extends the schema descriptions rather than merely repeating them.

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: 'Aircraft currently ARRIVING at an airport — live ADS-B' and specifies the output (inbound traffic with callsign, altitude, etc.). It distinguishes arrivals from siblings like get_departures and get_flights_in_area by focusing on inbound traffic to a specific airport.

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

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

Explicit usage guidance is provided with example queries ('Use for "what is landing at <airport> right now"') and a clear disclaimer ('This is a live picture, not a scheduled timetable'). It also warns about historical window limitations. However, it does not explicitly name alternative tools, so it falls just 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?

Beyond the readOnly/idempotent annotations, it discloses that no key is required for live data, explains the historical window credential/self-hosting constraint, and notes OpenSky unreachability from cloud egress—all useful behavioral traits not present in annotations.

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

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

The description is compact and front-loaded, starting with the core action, then giving examples, use cases, and a caveat. Every sentence earns its place with no redundancy or filler.

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

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

With an output schema and fully described parameters, the description covers the main use case, live-vs-historical distinction, and limitations. It provides enough context for an agent to decide when and how to invoke the tool.

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

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

Schema coverage is 100%, with detailed descriptions for every parameter (including credential requirements for begin/end and defaults). The description largely restates these, adding only contextual flavor like 'climbing out of the field' but no new parameter-level 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 returns aircraft currently departing an airport, listing specific fields like callsign, registration, and altitude. It explicitly uses 'DEPARTING' and mentions 'outbound traffic', distinguishing it from get_arrivals.

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 use cases ("what just took off from <airport>", "outbound traffic from <airport>") and warns it is a live picture, not a scheduled timetable. However, it does not explicitly name the alternative for arrivals (get_arrivals) or other 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 establish read-only, open-world, idempotent, and non-destructive behavior. The description adds 'No key required' (authentication context) and 'scheduled ROUTE' (clarifying it is schedule-based, not real-time), which go beyond the annotations. It does not cover error handling or rate limits, but with annotations this is adequate.

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

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

Four purposeful sentences: purpose, authentication note, concrete use cases, and sibling differentiation. No redundancy or filler; the key verb and resource appear 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 single-parameter lookup with no output schema, the description adequately covers input, output (airline, route, airports, codes, coordinates), use cases, and access requirements. It is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% and the parameter description already defines callsign as ICAO or IATA form with examples. The tool description repeats the same examples ('UAL1', 'BAW117') without adding additional semantic meaning beyond the schema.

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

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

The description uses the specific verb 'Resolve' and identifies the resource (flight callsign) and output (airline and scheduled route with airports/codes/coordinates). It explicitly differentiates from sibling get_flights_in_area, making the tool's role clear.

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: 'where does flight X fly from/to', 'what route is <callsign>', and 'which airline is <callsign>'. It also names get_flights_in_area as the complementary tool for overhead callsigns, giving a clear alternative.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context beyond annotations: data is 'LIVE ADS-B', 'no key required', and it lists the exact return fields including emergency code. This provides useful operational context not present in the annotations, though it doesn't mention potential delays or limits beyond the schema's limit parameter.

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, data source, return fields, use cases, and sibling alternatives. It is slightly long but front-loaded and free of filler, making it efficient and well-structured.

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

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

Given the tool complexity (5 params), rich annotations, and presence of an output schema, the description covers all necessary context: what it does, when to use it, what it returns, and how it differs from siblings. No critical information is missing.

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

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

Schema coverage is 100%, so the description does not need to document parameters. The description only mentions 'bounding box' conceptually and does not add extra meaning beyond the schema's already-complete property descriptions. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Find'), names the resource ('aircraft currently airborne in a geographic area'), and specifies the method ('by bounding box'). It also distinguishes itself from siblings by naming get_aircraft and get_flight_route as alternatives for different use cases.

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

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

Provides explicit use cases ('what planes are over <place> right now', 'aircraft near <airport>', 'is anything squawking 7700 near X') and explicitly names alternatives ('For one known aircraft use get_aircraft; for what route a callsign flies use get_flight_route'). This gives clear when-to-use and when-not-to-use guidance.

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

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

With annotations declaring readOnlyHint, idempotentHint, and openWorldHint, the description adds value by specifying it returns only the caller's subscriptions and that include_inactive defaults to false. It also lists the exact fields returned, which compensates for the lack of an output schema. 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 only two sentences: the first states the action and output fields, the second gives usage guidance. All content is relevant and there is no fluff, earning a top 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?

For a simple read-only list tool with one optional parameter and rich annotations, the description is complete. It covers purpose, returned fields, and usage context; the lack of an output schema is mitigated by listing fields inline. Some might want pagination info, but the low complexity makes this acceptable.

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 fully documents include_inactive with its default value (100% coverage), so the baseline is 3. The description does not elaborate on the parameter, but it does hint that cancelled subscriptions might be relevant when finding an id to cancel. Since the schema is explicit, no additional semantic burden is placed on the description.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and enumerates the returned fields (id, type, params, created_at, etc.). This distinguishes it from mutation siblings like subscribe/unsubscribe and other monitoring tools.

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

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

The description explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' giving clear when-to-use context. It doesn't explicitly name alternatives, but it aligns with subscribe/unsubscribe siblings, making the usage intention unambiguous.

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

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

With all annotation hints false, the description carries the transparency burden. It discloses rate limits (5 per day), the claim_token return flow, and that feedback doesn't count against quota. It also advises not to paste end-user prompts, implying privacy care. Missing explicit statement about data retention or human reading, but 'team reads digests daily' 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 longer than typical, but every sentence earns its place—purpose, usage exclusions, token flow, rate limits, and a 'not sure?' helper. It's front-loaded with the primary action and contains no fluff, though it could be tightened.

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 explains the key return behavior (claim_token on filing without account, status on later lookup). It covers the main feedback flow, exclusions, and limits. It doesn't describe response structure when filing with an account, but that's a minor gap.

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

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

Schema covers 100% of parameters, but the description adds meaningful operational detail: it explains the meaning of type values, the claim_token usage as a subsequent read call, and message guidelines to reference Pipeworx tools. This goes beyond the schema's field descriptions.

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

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

The description opens with a specific verb ('Tell') and resource ('the Pipeworx team'), then enumerates the exact categories of feedback (bug, feature/data_gap, praise). It clearly distinguishes this tool from sibling tools by focusing on reporting issues with Pipeworx tools themselves rather than querying or researching.

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

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

The description gives explicit when-to-use guidance (bug, feature gap, praise) and when-not-to-use, including a strong exclusion for feedback about other MCP servers. It also explains the claim_token follow-up mechanism, making it clear this is for Pipeworx-specific feedback only.

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

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

The description adds meaningful behavioral context beyond the annotations: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' It discloses data origin, caching behavior, and privacy characteristics. Combined with the readOnly/idempotent hints, this gives a solid picture without contradicting annotations.

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

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

The description is moderately sized but well-structured, starting with a clear one-line summary followed by a bulleted list of use cases and a final note on data source/caching. Each sentence adds value, though the 'Useful for' list could be slightly tightened. Overall, it is efficient 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?

Given the tool's simplicity (one optional parameter, no output schema), the description is complete: it states what is returned, the windows available, use cases, data derivation, privacy, and caching. No other behavioral or contextual aspects appear missing. The annotations and schema complement the description well.

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 single parameter `window` is fully documented in the schema with enum values and descriptions. The tool description repeats the window options ('24h, 7d, or 30d') but does not add new semantic details beyond what the schema already provides. With 100% schema coverage, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window.' It uses a specific verb ('Returns') and names the resource ('Pipeworx'), distinguishing it from siblings like discover_tools by focusing on what other agents are calling. The opening sentence immediately conveys the core purpose.

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

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

The description provides three explicit 'Useful for' scenarios: discovering hot data sources, confirming canonical tool choice, and checking alignment with agent needs. This is clear context for when to use the tool, though it does not mention specific alternatives or exclusions. While it lacks a direct comparison to siblings, the use cases make the intended application 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 the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses critical behavioral traits: the partition_check logic (sum of YES prices ≈1, deviations >3pp emit a signal), the FILL CHECK that prices against live CLOB depth and warns when realizable_edge_pp ≤ 0, the SEMANTIC ANCHOR threshold (≥0.30 Jaccard similarity), and the PARTITION FILTER behavior (placeholders >20% return null). These details tell the agent exactly what happens under various conditions, far exceeding the annotation baseline.

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

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

Although the description is long, it is densely packed and well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that make it scannable. Every sentence adds necessary operational detail for a complex tool. The opening sentence immediately conveys the core action, and the response format is included, saving the agent from guessing return values. 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?

The tool has no output schema, so the description compensates by specifying the response structure: opportunities[] with fields (gap_pp, suggested_trade, reasoning, monotonicity violation context), partition_check fields, and fill check details. It covers all modes, edge cases, and the meaning of null results. Given the tool's complexity, this description is remarkably complete, leaving no major ambiguity about invocation or interpretation.

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

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

The input schema already describes both parameters (event and topic) with examples. The description adds substantial meaning by explaining how each parameter changes the tool's behavior (single-event vs cross-event scanning), what kind of values to pass (event slugs like 'fed-decision-may-2026' or topic questions like 'Strait of Hormuz'), and what outputs to expect in each mode. This goes well beyond the schema's field descriptions.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (trending_scan, event, topic) and provides concrete examples, making it obvious what the tool does and how it differs from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description explicitly states when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also gives examples of slugs and seed questions, and even mentions an alternative tool: 'For custom sizing use polymarket_fill_risk.' This exceeds basic guidance by providing clear selection criteria and 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?

Beyond the generic annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses substantial behavior: caching at KV level for 1h keyed on knobs, model-family methodology, slippage handling, placeholder-slug filtering, rare-by-design longshot gates, the unreliable Fed-signal note, and diagnostics for empty segments. This is rich, honest behavioral disclosure with no contradiction.

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

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

The description is long but information-dense, with a clear front-loaded purpose and logical sectioning via ALL-CAPS labels. Some content overlaps with the schema's parameter descriptions, but each sentence adds operational context; minor tightening or bullet formatting could improve scannability.

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

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

With no output schema, the description compensates fully by documenting the response top-level structure (by_segment, fed_candidates/fed_note, _diagnostics), per-opportunity fields, and why segments may be empty. It also covers knob interactions and caching, making the tool's behavior and response shape unambiguous 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?

The schema already covers all 9 parameters (100% coverage), but the description adds meaningful semantics beyond the schema: edge is 'NET of slippage', slippage_pp is subtracted 'before ranking and Kelly sizing', max_spread_pp and min_liquidity are explicitly 'Tradeable-edge filters', and min_partition_leg_kelly clarifies why parent-level kelly is zero and how the per-leg filter works. This helps the agent choose parameters correctly.

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-outcome: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also states the intended use case ('what should I bet on today') and describes the output segments, making it clearly distinct from sibling tools like polymarket_arbitrage or 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 gives clear context for when to use the tool ('agents discover opportunities without paging hundreds of markets') and explains tradeable-edge knobs that shape invocation. However, it does not explicitly name alternatives or state when NOT to use it (e.g., for tracking edges over time or cross-platform arbitrage), so it falls just short of the highest bar.

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

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

The description goes well beyond the annotations (readOnlyHint, idempotentHint) by detailing response structure, the meaning of expired opportunities, snapshot date gaps, the 60-day TTL limitation, and the computation of decay numbers from daily closes. This rich context is highly valuable and does not contradict any annotations.

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

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

The description is well-structured with Args, RESPONSE, and LIMITS sections. Every sentence contributes meaningful information, and the purpose is front-loaded. Despite its length, it is densely packed and not wasteful.

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

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

With no output schema, the description fully explains the return values (tracked[], expired[], snapshot_dates[]) including field details. It also covers limitations, prerequisites, and edge cases (snapshot gaps, TTL), making the tool's behavior and expectations clear for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'snapshot family' concept for the window parameter and how days affect the response (e.g., snapshot_dates shows actual data availability). It reinforces defaults and clamps, which helps but is somewhat redundant with 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 specific purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a concrete question ('how long has this edge existed and is it shrinking?'). It distinguishes itself from sibling tools like polymarket_edges by focusing on the time dimension and decay analysis, not just current edge values.

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

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

The description gives strong contextual guidance: it explains that a fresh edge and a 3-week-old edge are different trades, implying when historical persistence matters. It does not explicitly name alternatives or state when-not to use the tool, but the context is clear enough for an agent to infer appropriate use cases.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. The description adds extensive behavioral context: how size_usd is interpreted differently for buys vs sells and single vs basket mode, the list of outputs (slippage_pp, capture_ratio, thin_legs, forced_directional_risk), and the risk of partial fills. No contradiction with annotations; it enriches them.

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

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

Long but well-organized with ALL-CAPS section markers (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) that make it scannable. Every sentence carries technical meaning—no filler, no repetition of schema/annotations—and the structured format earns the length.

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

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

The tool is complex with two modes and no output schema, yet the description thoroughly covers inputs, outputs, edge cases (thin_legs, forced_directional_risk), and failure modes. It even explains the significance of partial fills and stranded positions, giving the agent a complete mental model of the tool's behavior and limitations.

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

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

Schema already covers all 4 parameters with detailed descriptions (100% coverage). The description further clarifies semantics: size_usd is 'max spend on buys, target proceeds on sells' in single-market, and 'settlement notional S (shares per leg)' in basket mode. It also explains the auto-side default for baskets, adding value beyond the schema.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes the two modes (single-market vs basket) and explicitly connects itself to sibling tools (polymarket_arbitrage, polymarket_edges) by positioning as a pre-trade validation step.

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 criteria: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale (theoretical overround on thin books is not capturable, partial basket fills convert arb into unhedged directional position), effectively guiding agent decision-making.

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

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

The description goes well beyond the readOnly/idempotent annotations by detailing the response fields (leg-by-leg prices, spread direction), the two compatibility_warning cases, temporal_alignment semantics, and skipped_cross_type/subtype counters. It also warns that most pre-mapped topics currently return warnings, setting accurate expectations.

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 appropriately structured and front-loaded. It starts with purpose, then modes, response fields, safety flags, and a cautionary note. Every sentence adds distinct value, and the complexity of the tool justifies the length.

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

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

Despite having no output schema, the description compensates by explaining the full response shape and all safety fields, including edge cases like non-equivalent bet shapes and temporal gaps. It also sets expectations about tradeability, making it complete for a complex tool.

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

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

The schema already provides 100% coverage with descriptions for all three parameters. The description adds value by explaining the two-mode behavior and the override semantics (explicit ticker/slug overrides the topic-mapped side), but much of this is also present in the schema, so it earns a 4 rather than a 5.

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

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

The description clearly defines the tool as computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies the exact resource and concept, and distinguishes itself from sibling tools by naming the two venues and the spread signal.

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

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

The description explains two usage modes (pre-mapped topic shortcuts and explicit event pairings) and provides clear context for when the output is meaningful vs. meaningless (e.g., compatibility_warning, temporal_alignment). However, it does not explicitly contrast this tool with alternatives like polymarket_arbitrage, so only a 4.

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 (read-only, idempotent, non-destructive), the description discloses scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the list-all-keys behavior when the key is omitted. This adds useful context without contradicting annotations.

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

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

The description is three sentences with no fluff, front-loading the primary action and then providing usage guidance and scoping information. 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?

For a simple read-only tool with one optional parameter, the description fully covers purpose, usage, scoping, and companion tools. No output schema exists, but return behavior is implied and adequate for this tool's complexity.

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

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

Schema coverage is 100% with a clear parameter description, but the tool description adds further meaning by explaining that omitting the key lists all keys and providing example key contents (ticker, address, research notes). This goes beyond the schema's basic definition.

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 retrieves a previously saved value or lists all saved keys when the key argument is omitted. It uses a specific verb (retrieve/list) and resource (memory), and distinguishes itself from siblings like remember and forget.

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

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

It explicitly says to use this tool for looking up stored context without re-deriving it, and pairs it with remember (to save) and forget (to delete). This makes the usage context and alternatives clear.

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

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

There is a direct annotation contradiction: annotations mark readOnlyHint:true, but the description explicitly describes mutation via 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This is a state-changing operation, conflicting with read-only semantics. The idempotentHint is also questionable when mark_read is used repeatedly. Such contradictions confuse the agent about side effects.

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

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

The description is three sentences, each earning its place: the first states the core function, the second details return contents, and the third covers filtering, mark_read, polling, and an alternative endpoint. It is compact, front-loaded, and contains no fluff.

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

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

The description covers the return payload (source, citation_uri, raw event payload), filtering options, mark_read side effects, polling suitability, and an external endpoint. No output schema exists, so the description carries the burden of explaining return values, which it does. However, the contradiction with readOnlyHint leaves a completeness gap regarding side effects, though the description itself is fairly comprehensive.

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

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

Schema coverage is 100% with descriptions for all five parameters. The description adds value by providing an example for type ('sec_8k'), clarifying since as 'ISO timestamp,' and explaining the broader effect of mark_read: 'so the next call only shows newer ones.' It also mentions the return payload fields, though those are not parameters. This goes beyond the schema's basic descriptions.

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

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

The description starts with 'Pull fired events from your subscription feed,' which clearly identifies the verb (pull) and resource (subscription feed/alerts). It also distinguishes itself from sibling tools like list_subscriptions and subscribe by focusing on retrieving fired events.

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

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

The description provides clear context for use: filtering by type/since, setting mark_read for polling new events, and noting that 'Polls work fine.' It also suggests an alternative for scripts/dashboards via 'GET registry.pipeworx.io/alerts.json.' It does not explicitly exclude other use cases or name sibling alternatives, but the guidance is clear.

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

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

The description discloses significant behavior beyond the readOnly/openWorld/idempotent annotations: fan-out to SEC EDGAR, GDELT/GNews fallback logic, USPTO soft-fail due to PatentsView API sunset, and the exact return shape (changes[] grouped by source, total_changes, citation URIs). This contextualizes what happens during execution without contradicting the annotations.

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

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

Despite its length, the description is tightly packed with indispensable information. It front-loads the user intent, then explains the multi-source fan-out, parameter format, return structure, and closes with an explicit alternative tool. No sentence is wasted; the density is justified by the tool's complexity.

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

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

With no output schema, the description compensates by detailing the return value structure (changes[], total_changes, citation URIs). It also covers edge cases (API sunset, fallback conditions) and the only supported entity type. Combined with the rich annotations and full parameter schema, the description provides a complete operational picture.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by providing concrete examples for 'since' ('7d', '30d', '3m', '1y') and noting typical monitoring values ('Use "30d" or "1m"'), which the schema does not include. It also reinforces the 'type' enum and 'value' format, making the parameter guidance more actionable.

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

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

The description clearly defines the tool as a 'change feed' for a company over a time window, with concrete query examples like 'What's new with X' and 'updates on Acme'. It explicitly distinguishes from the sibling tool entity_profile by stating when to use that instead, making the purpose unambiguous.

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

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

It provides explicit usage context with natural language examples and a direct alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also describes when fallback sources are used (e.g., GDELT preferred, GNews on rate-limit/5xx), which helps an agent decide when to invoke this tool.

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

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

The description adds valuable behavioral context beyond the annotations: key-value pair scoped by identifier, persistent for authenticated users, and 24-hour retention for anonymous sessions. This is meaningful supplementary information that helps the agent understand side effects and scope.

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

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

The description is concise and front-loaded with core purpose. Every sentence adds value, from primary action to usage context to persistence caveats to tool pairings. No superfluous wording.

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 key-value storage tool with 2 well-documented parameters and no output schema, this description covers all essential dimensions: what it does, when to use it, how it behaves (scope, persistence), and how it relates to sibling tools. It is complete for an agent to select and invoke correctly.

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

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

The schema already provides descriptions for both key and value (100% coverage). The description enriches this with context about the kind of content to store ('resolved ticker, target address, user preference'), which helps the agent choose appropriate keys and values in practice.

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 saves data for reuse later, using a specific verb ('Save') and resource ('data'). It distinguishes itself from sibling tools by explicitly mentioning recall and forget as complementary 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 when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples like 'a resolved ticker, a target address, a user preference, a research subject.' It also names alternatives (recall, forget) and their purposes.

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

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

The description adds significant behavioral context beyond annotations: LEI/FIGI enrichment degrades gracefully, unresolved identifiers are explicitly listed, each call cascades through multiple endpoints, and every identifier is source-labelled. These details are not present in the annotations and greatly aid agent understanding.

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

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

The description is well-structured, with a list of example queries, a clear purpose statement, and distinct sections for each supported type. It is lengthy, though every sentence adds value; the opening example list could be trimmed to improve front-loading of the core purpose.

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

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

With no output schema provided, the description thoroughly explains what each entity type returns, including specific identifiers, ownership information, and citation links. It also covers failure modes like graceful degradation and explicit unresolved identifiers, making it complete for a tool of this complexity.

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

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

The schema already covers 100% of parameters with clear descriptions, and the tool description mostly repeats those details (e.g., company accepts ticker, CIK, or name). It adds only marginal extras like the CIK being 10 digits; the richer details are about output behavior rather than parameter meaning.

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 precisely states the tool's function: resolving a user-spoken NAME to canonical/official identifiers. It lists concrete example queries, explicitly names supported types (company, drug), and distinguishes it from sibling tools by saying 'Use FIRST whenever you have a name but need an ID.'

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

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

The description provides explicit guidance with 'Use FIRST whenever you have a name but need an ID' and notes it replaces 2-3 manual lookups, making its primary use case clear. However, it doesn't mention when not to use it or name alternative tools, so it stops short of full when/when-not guidance.

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

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

Annotations already indicate readOnly/idempotent/non-destructive, and the description adds behavioral detail: it probes with ai_visibility_check, ranks by score, and returns score, confidence, and signal density. This goes beyond the annotation hints, though it does not mention potential multi-call cost or rate limits.

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

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

Three sentences: front-loaded purpose, process, use case, and return summary. Every sentence carries distinct information with 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?

Despite having no output schema, the description explains the return format (ranked list with score, confidence, signal density). It also gives a concrete use case and example, making it easy to understand when to invoke this tool. No critical gaps for a comparative read-only operation.

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

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

The input schema already provides comprehensive descriptions for all parameters (100% coverage), including the first-entity-as-subject rule and model options. The tool description adds minimal new parameter meaning, so it appropriately relies on 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: 'Compare AI visibility across multiple entities side-by-side.' It specifies the resource (AI visibility) and the action (compare/probe/rank), and distinguishes itself from sibling ai_visibility_check by focusing on multiple entities and ranking them.

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 a specific use case ('competitive AI-marketing audits') and an illustrative example query. It implicitly differentiates from ai_visibility_check by saying it 'probes each entity...' and returns a ranked list, but does not explicitly state when not to use it or name alternative tools for single-entity checks.

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 valuable non-obvious behavioral details: bundlephobia's first measurement can take 5-30s, partial failures degrade gracefully via a 'sources_failed' field, and the specific output fields are listed. 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?

Every sentence earns its place: main purpose, use cases, return summary fields, ecosystem scope, and failure behavior. The description is front-loaded with the core purpose and remains information-dense without wasting words, given the tool's complexity.

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

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

Despite having no output schema, the description enumerates the summary block fields, per-advisory detail, links, recent alternative versions, and handles edge cases like timeouts and partial failures. It gives an agent sufficient context to know exactly what will happen and when to use the tool.

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

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

Schema coverage is 100% with both parameters fully described ('package' and 'version'). The description does not add parameter-specific semantics beyond what the schema already states, e.g., 'Defaults to the latest published version' is already in 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 a composite npm package evaluation tool with a specific verb ('scan') and resource ('dependency'), explicitly framing it as a 'should I add this npm package' check. It distinguishes itself from any sibling by naming its two data sources (deps.dev and bundlephobia) and the consolidated return.

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

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

Provides explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also clearly scopes to the npm ecosystem and directs non-npm ecosystems to 'deps.dev:version directly', which serves as an alternative tool route.

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 with readOnlyHint/idempotentHint annotations, the description adds significant behavioral detail: the exact embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), similarity metric (cosine), and a 200K-character cap with truncation-and-flag behavior. This transparency helps an agent predict output quality and avoid size-related surprises.

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?

At roughly 120 words, the description is dense yet every sentence earns its place. It front-loads the core purpose, then covers usage, pairing, and technical constraints in a logical flow, with no redundant or filler language.

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

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

The tool has no output schema, so the description correctly carries the burden of describing the return format — 'top-N passages with character offsets and similarity scores.' Combined with the truncation cap and pairing guidance, the description gives an agent all the contextual information needed to choose and invoke the tool effectively.

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

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

The input schema already provides 100% coverage with detailed descriptions for text, query, and limit (including max length, default, and query examples). While the description reinforces roles via phrases like 'text you already pulled' and 'natural-language query,' it introduces no new parameter-level semantics beyond what the schema already contains. It meets the baseline but does not elevate it.

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

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

The description opens with the precise verb-resource phrase 'Semantic search INSIDE a fetched record,' immediately distinguishing it from broader search tools. Concrete examples (SEC 10-K, article, long tool result) further anchor its niche, and the contrast with 'too big to cram into the prompt' makes the purpose unmistakable.

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

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

It explicitly states the triggering condition — 'Use when the record is too big to cram into the prompt' — and highlights the context-saving benefit. It also names ask_pipeworx_grounded as a complementary sibling and describes how to chain it, which is actionable guidance beyond a generic list of 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?

The description goes far beyond annotations by disclosing concrete operational behaviors: authentication requirements, phone verification for SMS, a 10/day cap, webhook auto-disable after 10 consecutive failures, and a one-time HMAC signing secret. These details are absent from the annotations and are critical for understanding side effects and constraints.

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

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

Despite the length, every sentence earns its place: purpose, return value, OAuth requirement, type examples, delivery options with specifics. The information is dense but organized, front-loaded with the primary purpose, and uses colons and parentheticals to pack examples without redundancy. It is appropriately sized for a tool being described to an AI agent.

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 explicitly covers the return value ('Returns the new subscription id'). It addresses prerequisites, all supported subscription types with parameter examples, delivery channels, and constraints like phone verification and SMS limits. The nested parameter structure is well-explained, making the tool fully usable from the description alone.

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

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

The input schema already provides 100% coverage with detailed descriptions for each parameter, setting a baseline of 3. The description adds tangible value with concrete examples like items:['5.02'] = officer change for sec_8k, topic:'fed' for polymarket_edge, and series_id:'UNRATE' for fred_series, which clarify semantics beyond generic schema text. However, since the schema already covers most type-specific details, the marginal gain is not enough for a 5.

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

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

The description opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' This clearly distinguishes it from sibling tools like list_subscriptions (viewing existing) and unsubscribe (removing), and the mention of 'Returns the new subscription id' completes the core 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?

It explicitly states prerequisites and exclusions: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' It also provides guidance on when to pull instead of subscribe by mentioning 'feed (always on — pull via recent_alerts or GET registry.pipeworx.io/alerts.json)', and enumerates supported types with examples, helping the agent select the right subscription type.

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

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

The description adds behavioral context beyond annotations by explaining that the output is derived from the 'live catalog of thousands of tools' and that results include tool+argument shapes. It also describes the effect of passing vs. omitting the topic parameter. Annotations already declare read-only/idempotent, but the description enriches the understanding of response content.

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

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

The description is moderately long but front-loaded with common user queries, then pivots to purpose, output, and usage. While every sentence adds value, the list of categories is somewhat expansive and could be trimmed. Overall, it's efficient and well-structured for an onboarding 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?

The description is complete for an onboarding tool with no output schema: it fully explains the return format (category-bucketed example questions), parameter behavior, and when to use it. Rich annotations cover safety and mutability. A small gap is the lack of limits or pagination details, but this is unlikely to be critical for an entry-point tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only reiterates what the schema states (omit for full spread, pass topic to focus) without adding new semantic detail. The examples in the description ('finance', 'pharma', 'betting') mirror the schema's enum-like values and do not enhance meaning beyond it.

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

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

The description clearly states the tool's purpose with a specific verb+resource: it is the onboarding entry point that returns category-bucketed example questions with the exact tool+argument shape. It distinguishes itself from sibling tools by explicitly positioning itself as the 'getting started' entry point, not a general search or discovery tool.

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

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

Explicit usage guidance is provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This directly tells the agent when to invoke this tool over alternatives and names the meta-tools it helps learn, making the decision clear.

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

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

Annotations already mark readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral details beyond annotations: ownership enforcement and that the row is deactivated (not deleted), which is a non-obvious side effect. No contradiction with annotations.

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

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

Three sentences, each serving a purpose: action, ownership, and deactivation consequence with a pointer to recent_alerts. Front-loaded with the core verb, no wasted words.

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

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

For a simple single-parameter tool with strong annotations, the description covers action, ownership, and side effects. It omits explicit error behavior (e.g., what happens if the id is not found or not owned), but this is a minor gap 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 fully documents the 'id' parameter as 'Subscription id (uuid) returned by subscribe' (100% coverage). The description adds the constraint that it must be your own subscription, giving extra semantic meaning beyond the schema.

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

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

The description opens with 'Cancel a subscription by id' — a specific verb and resource. It clearly distinguishes from siblings like subscribe (create) and list_subscriptions (list) by focusing on cancellation, and adds the ownership constraint for further clarity.

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

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

The description implies the tool is for canceling your own subscriptions and clarifies that historical events remain available via recent_alerts, which guides when to use it. However, it does not explicitly contrast with subscribe or list_subscriptions, relying instead on context from sibling names.

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 (readOnly, idempotent) are supplemented with deep behavioral detail: the internal routing to SEC EDGAR vs grounded pipeline, the full verdict list, and a critical warning that 'could_not_verify' indicates a failed check (not evidence) while 'unsupported' means no source found. 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?

Though longer than typical, it is efficiently organized: starts with trigger phrases and purpose, then usage, behavioral details, return values, an IMPORTANT caveat, and a note on efficiency. Every sentence earns its place, and the structure helps the agent quickly grasp key semantics.

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?

Compensates for the lack of an output schema by listing all possible verdicts, explaining the meaning of could_not_verify vs unsupported, describing the return value (with citation and reasoning), and clarifying the composite nature (replaces 4–6 calls). No critical information is missing for a complex tool.

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

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

Schema description coverage is 100% for both parameters. The description adds context about tolerance override (e.g., 'set 1–2 for hallucination detection') but the schema already explains the parameters well, so the description provides marginal additional 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?

States a specific verb+resource+scope: 'natural-language claim verification against authoritative sources.' Trigger phrases ('fact check', 'verify the claim that…') make intent unmistakable. Distinct from sibling tools by describing two pathways (SEC EDGAR structured vs grounded pipeline), clearly differentiating it from general Q&A or research 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 says 'Use whenever the agent needs to check whether something a user said is factually correct' and gives guidance for company-financial vs other claims. Lacks explicit when-not-to-use or named alternatives, but provides clear context and even notes it replaces 4–6 sequential calls, which is strong usage guidance.

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