Tfl

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: cost model (Workers AI free, Anthropic requires BYO key with direct payment), and the return structure (per-model score, confidence, signals, raw_response, combined view). This goes beyond what annotations provide.

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

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

The description is three sentences, front-loaded with the main purpose. Every sentence adds critical information without redundancy. No unnecessary words or repetition.

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

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

Given the tool's complexity (4 parameters, no output schema but return structure described), the description covers purpose, parameters, return shape, and use cases. It is complete enough 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?

All 4 parameters are documented in the schema (100% coverage). The description adds semantic value by explaining defaults (models omitted = workers-ai), the role of `_apiKey`, and the purpose of `context` for disambiguation.

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: probing LLMs for knowledge about an entity and scoring visibility per model. It specifies the default model and condition for Anthropic, and distinguishes it from siblings like 'compare_entities' and 'scan_competitor_ai_presence' by its focus on multi-model visibility scoring.

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

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

The description provides explicit use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. However, it does not directly compare with sibling tools or state when NOT to use it, but the listed scenarios give clear guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds context: 'real-time', 'predicted arrivals', 'sorted by timeToStation (seconds away)'. No contradictions.

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

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

Two sentences, front-loaded with purpose. No extraneous words. Every sentence adds value.

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

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

Single-parameter read-only tool with strong annotations. Description sufficiently covers purpose, input source, and result sorting. No output schema needed.

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

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

Schema coverage is 100% and already describes naptanId as obtained from stop_search. Description adds an example value but does not fundamentally expand meaning beyond schema. Meets baseline with minor enhancement.

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

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

Description clearly states 'Real-time predicted arrivals at a stop.' with specific verb 'arrivals' and resource 'stop'. It distinguishes from siblings like stop_search (which returns stops) and plan_journey (journey planning).

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

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

Explicitly instructs to pass the naptanId from stop_search, providing a prerequisite. Mentions sorting order but no exclusion conditions or alternative tools. Adequate for a simple read tool.

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

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

Annotations already declare this is read-only, idempotent, and non-destructive, so the description does not need to repeat that. It adds meaningful behavioral context beyond annotations: the tool routes to internal tools, fills arguments, returns structured answers with citation URIs, works on every tier, and makes one fast call. It could additionally describe failure or ambiguity behavior, but the existing context is strong.

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

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

The description is long but well-structured: it opens with the most important instruction (prefer over web search), states the mechanism, gives trigger phrases and examples, and then routes to alternatives. The example list is extensive but useful. It could be slightly tightened, but it is not redundant or 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?

Given that there is no output schema, the description compensates by describing the return format (structured answer with stable pipeworx:// citation URIs). It covers the tool's scope, trigger phrases, examples, tier availability, speed, and related alternatives. An agent has enough context to decide when to call this tool and what to expect from it.

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

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

The input schema has 100% coverage: the `question` parameter is described as natural language and all aliases are explicitly named. The description adds usage examples and a trigger phrase list, but it does not add new meaning about the parameter beyond what the schema already provides. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description clearly states the tool's function: it routes factual questions to one of 5,718 tools across 1,496 verified sources and returns structured answers with stable citation URIs. It is explicitly differentiated from siblings like ask_pipeworx_grounded and deep_research, so an agent can immediately tell what this tool does and where it fits.

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: "PREFER OVER WEB SEARCH," "Use whenever the user asks..." and "START HERE for most questions — this is the default entry point." It also names concrete step-up alternatives: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions, leaving no ambiguity about routing.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description reveals live candidate routing improvements, that none are active as of 2026-07-26, that it falls back to nothing, and that it is a fully working router rather than a stub. This is exceptionally candid about experimental 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?

Every sentence carries distinct information: beta relationship, candidate behavior, current no-active-candidate state, usage instruction, evaluation purpose, and fallback clarification. It is dense but not bloated, and key identity and usage details are front-loaded.

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

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

The description is largely complete for selecting and invoking the tool: it explains current behavior, exact parity with ask_pipeworx, and that it is a full router. However, it relies on ask_pipeworx's known behavior for response-shape details rather than describing the output itself, which is a minor gap given no output schema is present.

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

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

Schema description coverage is 100%, so the schema already documents all six parameter aliases and the natural-language question input. The description adds no parameter-level meaning beyond noting 'same arguments' as ask_pipeworx, so the high-coverage baseline applies.

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

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

Description clearly defines it as the beta version of ask_pipeworx, an identical universal router with the same 5,718 tools, arguments, and response shape. It explicitly distinguishes it from the stable sibling by labeling it the experimental edge.

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

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

States when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies current status—no active candidate, so it matches ask_pipeworx exactly—and notes results are compared against the stable router to decide merges.

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

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive hints. The description goes well beyond: it details the extraction process, the structured success response, the explicit refusal reasons, and the cost implication. None of this contradicts annotations, and it discloses behaviors an agent needs to handle refusal scenarios.

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 purpose, then the mechanism, return format, use cases, and cost trade-off. It is structured to be scanned quickly, with no fluff or repetition.

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

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

The tool is complex—it routes, extracts, and refuses—and the description covers all necessary aspects: the return object with evidence and refusal reasons, the cost side-effect, and when to prefer the cheaper sibling. No output schema exists, so the description adequately compensates by specifying the exact return shape.

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

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

Schema coverage is 100% with all six parameters being aliases for a single question field. The description adds nothing beyond what the schema states; it simply refers to 'question' in the return structure. Since the schema fully documents parameter semantics, a baseline of 3 is appropriate.

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

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

The description opens with a precise purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly identifies the verb (answer), resource (Pipeworx data), and the distinguishing behavior (extraction only from tool results). It explicitly names its sibling ask_pipeworx to differentiate, 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?

It gives explicit when-to-use ('whenever an answer will be quoted, cited, or acted on') and when-not-to ('prefer ask_pipeworx for casual lookups'), directly comparing to the sibling tool. It also quantifies the trade-off (one extra LLM call), enabling an informed decision.

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, etc. The description adds extensive behavioral details: resolution process, fan-out logic, response shapes, safety short-circuits, and resolution-rule risk. No contradictions.

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

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

Well-structured with clear sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded purpose. However, it is lengthy and could be tightened without losing information.

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

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

Comprehensive coverage of behavior, response structure, edge cases, and safety mechanisms. Despite no output schema, the description fully compensates, making the tool well-understood.

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%. The description adds context beyond schema: explains market input types, depth options with defaults, and include_raw usage. Provides examples, which is valuable for parameter understanding.

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

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

Clearly states it researches a Polymarket bet by pulling data, with specific verb 'Research' and resource 'Polymarket bet'. Distinguishes from sibling tools like polymarket_edges by focusing on a single bet with in-depth fan-out.

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 like 'should I bet on X' and 'what does the data say about Y', but lacks explicit alternatives or when-not-to-use compared to sibling tools. However, the context is clear.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds that data is live and includes bikes available, spaces free, total capacity in additionalProperties. No contradictions; adds useful behavioral context.

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

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

Two concise sentences with no wasted words. Key information is front-loaded: what the tool does, what data it provides, and usage guidance for the optional filter.

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 low complexity (1 optional param, no output schema), the description is nearly complete. It explains what is returned (bikes available, spaces free, total capacity) and context (London cycle hire). Minor miss: not mentioning the output is a list of points, but implicitly 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?

Schema coverage is 100% (one optional parameter). Description adds meaning beyond schema by providing an example and clarifying that the parameter is an area filter. The example 'Clerkenwell' makes usage concrete.

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

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

The description clearly states the tool provides live bike and empty-dock counts for London Santander Cycle hire scheme, specifying the resource (docking points) and verb (counts). It distinguishes from siblings by being specific to London cycle-hire.

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 optional area filter usage and defaults to all docks when omitted. Provides example filter value 'Clerkenwell'. No explicit when-not or alternatives mentioned, but context is sufficient for typical use.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true. Description adds behavioral details: handles off-calendar fiscal years, returns sorted results by primary metric, includes citation URIs. 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?

Description is concise yet comprehensive, using bullet-like structure with trigger phrases upfront. Each sentence adds value, though slightly verbose due to detailed examples and sources.

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

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

Covers all aspects: trigger phrases, purpose, usage instructions, data sources, sort order, return format (paired data + citation URIs), and alternatives. No output schema, but return description is sufficient.

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

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

Schema coverage is 100%, but description adds meaning by explaining the purpose of each type (company pulls financials, drug pulls adverse-event data) and constrains value format (tickers vs drug names) and range (max 5 items).

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

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

Description starts with common trigger phrases and clearly states it performs side-by-side comparison of 2-5 companies or drugs in one parallel call. It distinguishes from sibling tools like entity_profile (single entity lookup).

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

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

Explicitly advises to prefer this tool over sequential single-pack lookups when comparing entities. Provides context on when to use (comparison, ranking) and explains data sources for each type (company: SEC EDGAR/XBRL; drug: FAERS).

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, and the description adds substantial context beyond that: account requirements, paid tier for 'thorough', latency expectations, the gaps[] array that never fabricates, citation_uri fetchability, contradictions[] behavior, and semantic excerpting. There is no contradiction with the annotations.

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

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

The description is long but information-dense, with every sentence contributing a distinct fact or guideline. Critical details like account requirements and the ask_pipeworx alternative are front-loaded. It could be restructured into clearer scannable sections, but there is no dead weight.

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

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

Without an output schema, the description fully compensates by detailing the return packet: verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], hop field, and citation_uri. It also covers auth, latency, and when the tool will underperform. For a tool of this complexity, an agent has everything needed to select and invoke it correctly.

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

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

Schema coverage is 100% for both parameters, so the parameter descriptions already document 'question' and 'depth'. The tool description nonetheless adds meaning by explaining how depth values affect hop behavior, gap recovery, and contradiction detection, and by clarifying that broad multi-part questions are intended. This is above the baseline of 3 but not a full 5 because the schema already carries the core 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 identifies a specific action and resource: 'Grounded multi-source research across Pipeworx's 1496 STRUCTURED data sources' and explains the decomposition/parallel routing behavior. It explicitly distinguishes itself from open-web search and from ask_pipeworx with concrete examples, so an agent can immediately tell what this tool does and what it is not.

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

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

The description gives clear when-to-use guidance: 'Best for broad/multi-part questions over structured data.' It also names the alternative ask_pipeworx for single lookups and breaking/current-news topics, and even states an account prerequisite with a fallback if not signed in. This is explicit, actionable routing information.

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 convey readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' 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 composed of two efficient sentences. The first sentence front-loads the purpose and use cases, and the second details output and usage order. Every sentence contributes meaning without redundancy.

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

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

Given the tool's simplicity (6 params, no output schema), the description covers purpose, usage guidance, output format, and call ordering. It does not explain relevance scoring or pagination, but these are minor gaps for a discovery tool. Sibling context further clarifies its role.

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 semantic value by clarifying that multiple parameters ('task, q, description, search') are aliases for 'query,' and specifies default and max for 'limit' (though schema already includes this). This goes beyond the schema's individual descriptions.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the verb 'find' and the resource 'tools,' and distinguishes from siblings as the only discovery-oriented tool in a list of domain-specific ones.

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

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

The description explicitly advises when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist for' various domains, and 'Call this FIRST when you have many tools available and want to see the option set.' It provides clear context but omits explicit when-not-to-use scenarios.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds 'current disruptions' and 'with description and affected lines', which is consistent but adds only modest behavioral context beyond annotations.

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

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

The description is a single, front-loaded sentence that efficiently conveys the tool's purpose and output. No extraneous words.

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

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

Given the tool's simplicity (one optional parameter, no output schema, no nested objects), the description fully covers what an agent needs: it retrieves current disruptions with description and affected lines. No missing context.

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

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

Schema coverage is 100% with the 'modes' parameter fully described (comma-separated modes, default 'tube'). The description restates 'given transport modes' without adding meaning beyond the schema.

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

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

The description clearly states 'Current disruptions for the given transport modes' with specific output fields 'description and affected lines'. It distinguishes well from sibling tools like 'line_status' and '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?

The description does not provide any guidance on when to use this tool versus alternatives like 'line_status' or 'arrivals'. It merely implies usage for disruptions without exclusions or context.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses behavioral traits: it fans out across multiple sources, details what is returned (cik, company_name, recent_filings with pipeworx URIs, fundamentals sorted, patents with a sunset note and soft-fail behavior, news via GDELT->GNews fallback, LEI). This adds significant context.

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

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

The description is informative and front-loaded with example queries, but it is somewhat verbose with a long list of examples and output details. While every sentence adds value, it could be slightly more concise.

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

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

Given the complexity of the tool (multiple sources and outputs) and the absence of an output schema, the description thoroughly explains what information is returned and any limitations (patents sunset, no name support). It provides a complete picture for an agent to understand the tool's capabilities 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?

The input schema already has descriptions for both parameters, but the description adds crucial meaning: 'Only "company" supported today' for type, and for value it explains ticker or zero-padded CIK and explicitly warns that names are not supported, directing to resolve_entity. This goes beyond the schema.

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

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

The description clearly states what the tool does: 'full cross-source profile of a US public company in ONE parallel call.' It enumerates the specific sources and outputs, and distinguishes itself from sibling tools by explicitly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news 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?

The description provides explicit usage guidance, including example queries ('Tell me about X', 'research Acme'), and states when to use: when the user asks for a holistic view. It also specifies when not to use by noting that names are not supported and directs to 'use resolve_entity first if you only have a name.'

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds behavioral context about when to use the tool (e.g., clearing stale or sensitive data) but does not elaborate further on side effects. This goes beyond annotations, meriting a high score.

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

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

The description is two sentences, front-loaded with the action, and every sentence adds value with zero redundancy or waste.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage, and relationships to siblings. It is complete and sufficient for an agent to use 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 description does not add additional meaning to the parameter 'key' beyond what the schema provides ('Memory key to delete'). Baseline 3 is appropriate as the schema already fully documents the parameter.

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

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

The description clearly states that the tool deletes a previously stored memory by key, using the specific verb 'Delete' and resource 'memory'. It distinguishes itself from sibling tools like 'remember' and 'recall' by mentioning 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?

The description explicitly provides usage context ('when context is stale, the task is done, or you want to clear sensitive data') and suggests pairing with related tools, giving clear guidance on when to use and alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds context beyond annotations by detailing the fetch, extraction, and output format steps, which helps the agent understand the tool's behavior without contradicting 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 three sentences long, front-loads the main purpose, then specifies the output format, and ends with usage examples. Every sentence adds value with no wasted words, making it highly concise 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?

For a tool with 2 parameters and no output schema, the description covers the core functionality, return format (single text blob), and use cases. It lacks details on error handling or edge cases, but given the annotations and schema richness, it is sufficiently complete for most scenarios.

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% from context signals, so the baseline is 3. The description mentions 'default 25, max 50' for max_links, which is already in the schema description, and reiterates the URL purpose. It adds no new semantic insight beyond the schema.

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

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

The description clearly states the verb 'generate' and the resource 'llms.txt file', and specifies the process (fetches page, extracts title/description/key links, emits markdown). It distinguishes from sibling tools by its specific output format and use case for AI crawler indexing, which no other sibling tool addresses.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting for own project, and auditing competitor indexing. It doesn't explicitly state when not to use, but the specific purpose is clear enough to guide appropriate 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 readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value by specifying the return format (lineStatuses + statusSeverityDescription) and giving example values like 'Good Service'. This is appropriate additional context.

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

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

Two sentences, no wasted words. Front-loaded with the purpose, then parameter usage, then return format. Perfectly concise for the information needed.

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 tool with no output schema, the description adequately covers the return format and parameter usage. It doesn't explain edge cases like missing parameters, but the schema shows they are not required. Slightly more detail on default behavior could improve it, but it's sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds that modes and lineId are alternatives and that lineId takes precedence. It also provides examples, which clarifies usage beyond the schema descriptions alone.

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

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

The description states 'Current service status for London transport lines', which is a specific verb+resource. It distinguishes from sibling tools like 'disruptions' which focus on incidents. The tool is clearly for querying live service status.

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 that you must pass either 'modes' or 'lineId', with examples. It doesn't explicitly state when to use this tool versus alternatives like 'disruptions' or 'arrivals', but the purpose is clear enough that an agent can infer usage context.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns specific fields like id, type, params, timestamps, and fire_count, and mentions the optional include_inactive parameter. No contradictions.

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

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

Two sentences front-load the purpose and return fields, then provide usage guidance. Every sentence is necessary and concise.

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

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

With one optional parameter, no output schema, and strong annotations, the description fully covers the tool's purpose, return data, and recommended usage. No gaps.

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

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

The description does not directly explain the include_inactive parameter, but the input schema provides a clear description (100% coverage). Baseline 3 is appropriate; the use case context adds some value but not parameter-level detail.

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 'List the caller's active subscriptions,' clearly stating the action and resource. It lists the return fields, which distinguishes it from sibling tools like subscribe, unsubscribe, and bet_research.

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

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

Explicitly states when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when it's appropriate versus alternatives.

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

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

Annotations are all false (readOnlyHint:false, etc.), providing minimal safety profile. The description adds critical context: filing without an account returns a claim_token for later lookup, rate-limited to 5 per identifier per day, free and not counted against tool-call quota, and the team reads digests daily. It discloses the two-step flow (file then check status with token), which is non-obvious and valuable. Minor gap: doesn't explicitly state whether the tool mutates state on the Pipeworx side or what happens to duplicate reports, but the included context goes well beyond annotations.

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

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

The description is a substantial paragraph but every sentence earns its place: purpose, scope exclusions, claim_token flow, rate limit, and quota exemption. It's front-loaded with the core action ('Tell the Pipeworx team...') and proceeds logically. Slightly longer than ideal but dense with high-value information; no redundancy.

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

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

This is a write-oriented feedback tool with no output schema and all-false annotations. The description compensates well by disclosing the two-step claim_token flow, rate limit, quota exemption, and daily digest behavior. It covers return value semantics (claim_token, status, changes). Minor gaps: doesn't specify if a response immediately indicates success/failure beyond the token, and the 'identifier' in rate limiting is ambiguous, but overall the description provides strong contextual coverage for a tool of this complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful behavioral semantics beyond the schema: it explains the claim_token's purpose ('Read the reply to a report you filed earlier'), the correct usage pattern (pass token with no other arguments), and the rate limit tied to 'identifier'. It also clarifies the context object's role ('Optional structured context: which tool, pack, or vertical this relates to') and message specifics. The enum descriptions in the schema already define types well, but the description's claim_token explanation adds non-obvious usage semantics, justifying a 4.

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

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

The description clearly states this tool sends feedback to the Pipeworx team about broken/missing/needed items, with a specific verb ('Tell') and resource ('Pipeworx team'). It lists concrete use cases (bug, feature/data_gap, praise) and explicitly distinguishes itself from sibling tools by noting it is ONLY for Pipeworx-served tools, not other MCP servers' 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 provides explicit when-to-use guidance: use for bugs, feature requests, data gaps, or praise. It explicitly says when NOT to use (for tools from other MCP servers) and gives a heuristic for identifying Pipeworx tools. It also explains alternatives (file with that server instead), making this a model example of 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 safety (readOnlyHint, idempotentHint), and the description adds valuable behavioral context: data source (CF analytics-engine), privacy (no PII), and caching duration (5min-1h). This goes beyond what annotations provide.

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

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

The description is concise with three sentences covering purpose, usage, and behavioral notes. It could be slightly more structured, but it is efficient and front-loaded.

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

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

Given the tool's simplicity (1 param, no output schema), the description fully explains inputs, outputs (top tools, packs, volume), and caching behavior. No gaps for an agent to use this tool correctly.

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

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

Schema coverage is 100% already describing the 'window' enum and its effect. The description adds guidance on selecting shorter vs longer windows, which enhances understanding beyond the schema.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over configurable windows (24h, 7d, 30d). It distinguishes from siblings by focusing on trending usage, not other analysis or search.

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

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

The description lists three specific use cases (discovering hot data sources, confirming canonical choices, alignment checking), providing clear context. It does not explicitly state when not to use or mention alternatives, but the context is sufficient.

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

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

Annotations already declare safe, idempotent, and non-destructive behavior. The description adds value by specifying that the output includes journey options with legs, durations, and modes, and that ambiguous locations trigger disambiguation responses instead of journeys. This enhances transparency beyond annotations.

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

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

The description consists of two efficient sentences. The first clearly states the tool's purpose, and the second covers input formats and an important edge case. There is no redundant information, and all content earns its place.

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

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

Given no output schema, the description adequately explains the return type (journey options with legs, durations, modes). It also covers ambiguous input behavior. While additional details like mode options or real-time data are omitted, the description is sufficient for a journey planning 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% with both parameters having descriptions. The description adds meaningful nuance by elaborating that from/to can be stop names, postcodes, or 'lat,lon' coordinates, and by noting the disambiguation behavior tied to ambiguous inputs. This exceeds the baseline of 3.

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

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

Description clearly states the verb 'Plan' and resource 'journey across London transport'. It distinguishes itself from siblings like arrivals, bike_points, disruptions, etc., by focusing on journey planning with flexible input types. The edge case of ambiguous locations is explicitly mentioned, adding precision.

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 usage: planning a journey across London transport with from/to inputs. It gives guidance on handling ambiguous locations by refining input or using more precise identifiers. However, it does not explicitly state when not to use this tool or list alternatives among siblings.

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

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

Annotations already declare readOnlyHint=true. Description adds fill check behavior explaining when not to trade (realizable_edge_pp ≤ 0), semantic anchor thresholds, and partition filter logic, providing transparency beyond annotations.

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

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

Description is long but every sentence adds value. Well-structured with clear sections (event mode, topic mode, semantic anchor, partition filter, response, fill check). Front-loaded with purpose, then detailed guidance.

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

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

For a complex tool with multiple modes and arbitrage logic, description covers inputs, output structure (opportunities[], partition_check, fill details), and important constraints. No missing context despite lack of output schema.

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

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

Schema coverage is 100% with descriptions. Description greatly expands on each parameter: explains event mode's per-event checks (date-axis, partition_sum), topic mode's cross-event scanning and Jaccard similarity, and fills in context not in 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (trending_scan, event, topic) with specific use cases, differentiating it from sibling tools.

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

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

Explicit guidance for each parameter: no args for trending scan, event for specific market (with example slugs), topic for cross-event scanning. Recommends event for specific markets and explains when cross-event mode is beneficial.

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

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

The description goes beyond annotations (readOnlyHint, idempotentHint, destructiveHint) by disclosing caching (1h KV-level), filtering logic (placeholder-slug filter, move warnings), diagnostic counters, and edge calculation details (slippage, Kelly fractions). This provides exceptional insight into tool 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 and technical but well-structured with clear segment labels and knobs. Every sentence adds value, though it could be more concise or use bullet points for readability. It is not overly verbose for its complexity.

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

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

Given no output schema, the description thoroughly explains response structure (by_segment, diagnostics), edge calculation, and knob behavior. It covers filters, caching, and empty-segment reasons, making it complete for accurate invocation.

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

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

Schema description coverage is 100%, so baseline is adequate. The description adds broader context (model families, filtering rationale) that helps interpret parameters like min_edge_pp and slippage_pp, but it does not elaborate on each parameter beyond what the schema provides.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market prices, and targets the use case 'what should I bet on today.' It is specific but does not explicitly differentiate from sibling tools like polymarket_arbitrage, though the focus on model-driven edges vs pure arbitrage provides implicit distinction.

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 says it is for discovering opportunities without paging hundreds of markets and explains when to use tradeable-edge knobs. However, it does not explicitly state when not to use this tool or compare it with alternatives, which limits guidance completeness.

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 extensive behavioral context beyond annotations: it details the response structure (tracked[], expired[], snapshot_dates[]), explains decay computation (on |edge_pp_net|), and notes limitations (decay from daily closes, not intraday). 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 well-structured with clear sections (response fields, limits) and front-loaded purpose. While it is long, every sentence adds essential information for correct usage; could be slightly more concise but effective.

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

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

Given the complexity (time-series data, multiple response arrays), no output schema, but description thoroughly documents all fields and edge cases (expired opportunities, snapshot gaps). It is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by specifying default values and meaning (e.g., 'window' as snapshot family, 'days' as lookback). It also clarifies the response fields, which compensates for lack of output schema.

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

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

The description uses a specific verb ('edge persistence and decay telemetry') and clearly distinguishes from sibling tools like polymarket_edges by focusing on the time-series aspect. It answers a concrete question: 'how long has this edge existed and is it shrinking?'.

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 this tool (to understand edge history vs. just the latest snapshot) and provides limits (60-day TTL, snapshotting start). It contrasts with the sibling tool polymarket_edges implicitly by focusing on persistence.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context: walks the ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, etc.), and explains forced directional risk. No contradiction. Minor omission of rate limits or auth requirements.

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 clear sections (REQUIRES, SINGLE-MARKET, BASKET) and every sentence provides essential info. Slightly long but justified by complexity. Could trim redundant phrases like 'forced_directional_risk naming the legs most likely to strand you unhedged' but overall efficient.

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

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

Despite no output schema, the description thoroughly explains return fields and risk warnings. It covers all four parameters, distinguishes modes, and provides sufficient context for an AI agent to correctly use the tool. Annotations cover safety, so no gaps remain.

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 parameter descriptions. The description adds meaning beyond schema: explains default size_usd=1000, side default auto for basket, and clarifies market vs event modes. Each parameter's role in single-market and basket modes is elaborated.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes with explicit details, differentiating it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about risks of partial fills and unhedged positions, providing clear context for use vs 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?

With readOnly/openWorld/idempotent annotations already covering safety, the description goes far beyond them: it discloses response shape, the meaning of compatibility_codes, the rule that unknown legs are never paired, how skipped counters behave, and that safety fields can be non-empty even when matches exist. This is rich behavioral context an agent needs 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 dense and long, but every section (modes, response, safety fields, codes, counters) adds operationally necessary information. It front-loads the core purpose and then layers detail; it could be more scannable with formatting, but it is not padded.

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

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

There is no output schema, so the description has to carry the return-value burden — and it does: it explains the per-leg prices, top_spreads_pp, compatibility_warning, codes, skipped counters, temporal_alignment, and low_confidence_pairs. For a three-parameter tool with a complex response, this is complete enough for an agent to call and interpret it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real value by explaining the topic shortcuts list, the override semantics of kalshi_event_ticker and polymarket_event_slug, and how the two modes interact. It doesn't redefine the schema but clarifies usage semantics sufficiently.

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

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

The description names a specific resource — the spread between Kalshi and Polymarket outcomes for the same resolving question — and gives the exact verbs: compute/compare and report compatibility. It is clear and specific, but it never names a sibling or says 'use this instead of X', so differentiation from polymarket_arbitrage or compare_entities is implicit rather than explicit.

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

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

The two-mode explanation ('topic' vs explicit ticker/slug) tells the agent exactly which parameters to supply for which scenario. The closing warning that most pre-mapped topics return compatibility_warning and that 'pre-mapped ≠ tradeable' is a strong when-to-be-cautious cue, but no alternative tool is named for cases where this comparison is the wrong choice.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds context about scoping (to identifier) and the behavior of omitting the key to list all keys, which is not covered by annotations. No contradictions.

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

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

The description is a single paragraph of three sentences, efficiently front-loaded with the core action. Every sentence provides essential information without redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description sufficiently explains the functionality, scoping, and pairing with siblings. It could mention the return format but is otherwise complete.

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

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

Schema coverage is 100% with a single parameter described. The description adds meaning by explaining that omitting the key lists all keys, which goes beyond the schema 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 uses a specific verb 'Retrieve' and identifies the resource as 'a value previously saved via remember' or 'list all saved keys'. It clearly distinguishes from sibling tools like 'remember' and 'forget' by stating the pairing and scoping.

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

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

The description explains when to use the tool: 'to look up context the agent stored earlier... without re-deriving it from scratch'. It also mentions pairing with 'remember' and 'forget'. However, it lacks explicit instructions on when not to use it.

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

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

Annotations declare readOnlyHint=true, but the description describes a write operation via the mark_read parameter ('flag returned events read'). This is a clear contradiction, as the tool modifies state despite being labeled read-only.

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 at 4 sentences, with the first sentence immediately stating the purpose. Every sentence adds value: return fields, filtering options, mark_read behavior, and an alternative method. 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 description covers the core functionality, return fields, parameters, and behavior of mark_read. It also provides an alternative access method. However, it does not discuss error handling, rate limits, or limit parameter behavior, though the schema covers limit. Given no output schema, it is largely sufficient but not exhaustive.

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 description adds meaningful context beyond the schema: it explains that 'type' filters by subscription type with an example ('sec_8k'), specifies 'since' expects an ISO timestamp, and details the effect of 'mark_read' (flags events read so next call shows newer ones). This supplements the 100% 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 pulls fired events from the subscription feed, specifies the return fields (source, citation_uri, raw event payload), and mentions filtering options. It is distinct from sibling tools like 'recent_changes' or 'subscribe' by focusing on alert 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 usage context by noting that polling works fine and provides an alternative URL for scripts/dashboards. However, it does not explicitly explain when to use this tool over other sibling tools like 'recent_changes' or 'subscriptions'.

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, destructiveHint. Description adds fan-out behavior, fallback strategy (GDELT→GNews), USPTO soft-fail, and return structure (grouped changes, total_changes, URIs).

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

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

Description is well-structured with examples first, then details. Slightly long but each sentence adds value; no redundancy.

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

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

No output schema, but description fully explains return structure and sources. Covers purpose, parameters, fallbacks, and alternative tool comprehensively.

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

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

Schema covers all 3 parameters at 100%. Description adds usage detail, e.g., '30d' or '1m' for monitoring, and value accepts ticker or CIK.

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

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

Description clearly states it's a change feed for a company in a time window, listing sources (SEC, GDELT, GNews, USPTO) and explicitly distinguishing from sibling entity_profile for static profiles.

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

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

Provides explicit when-to-use examples ('What's new with X') and directs to entity_profile for static profiles, with detailed since parameter 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 indicate idempotentHint=true and destructiveHint=false, which the description supports by stating 'stored as a key-value pair' and describing persistence (authenticated vs anonymous). It adds behavioral context beyond annotations, such as scoping by identifier and 24-hour retention for anonymous sessions.

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

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

The description is a single, well-formed paragraph. The first sentence states the core purpose, followed by usage guidance, then details on scoping and persistence. Every sentence contributes meaning with no redundancy.

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

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

Given no output schema, the description sufficiently explains the result (data is stored) and provides persistence details. It lacks mention of size limits or error cases, but for a simple memory tool with clear inputs, it is adequately 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 has 100% coverage with descriptions for both 'key' and 'value'. The description adds examples (e.g., 'subject_property', 'target_ticker') but does not significantly enhance meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' using key-value pairs. It distinguishes from siblings by explicitly mentioning 'Pair with recall to retrieve later, forget to delete.' The verb 'save' and resource 'data' are specific.

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

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

The description explains when to use: 'when you discover something worth carrying forward... so you don't have to look it up again.' It provides context (scoped by identifier, persistence based on auth) but lacks explicit when-not-to-use or alternative tools beyond recall/forget.

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

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

Annotations already declare read-only and idempotent behavior, and the description adds rich context: multi-source identity resolution, graceful degradation when GLEIF/OpenFIGI is unavailable, explicit unresolved identifiers, figi_candidates on ambiguous matches, and internal cascading lookups. There is 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?

Front-loaded with question patterns and a clear directive, but the body is a dense wall of text with long parentheticals that hurt scannability. Each detail is informative, so nothing is wasted, but the structure is not appropriately digestible for an 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?

Given no output schema, the description carries full responsibility for explaining results, and it does: CIK, ticker, company_name, LEI, ownership, FIGI, figi_candidates, unresolved fields, source labels, RxCUI, ingredient, brand, and citation. Inputs, ambiguity handling, and failure behavior are all 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?

Schema coverage is 100%, yet the description still adds strong semantic guidance: accepted input forms for company versus drug, ISIN-to-LEI behavior, and the crucial warning that a bond value must be the issuer name exactly as printed, not the full noun phrase. This goes well 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?

States a specific action — resolve a user-spoken NAME to canonical/official identifiers — and supports it with concrete example queries. It also positions itself as the input step for other tools, distinguishing it from downstream siblings like entity_profile and compare_entities.

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?

Gives an explicit rule: 'Use FIRST whenever you have a name but need an ID,' and enumerates supported types and accepted input formats. It does not name sibling tools or state when to prefer alternatives, but the core use case is clearly scoped.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds behavioral detail: probes each entity, ranks by score, returns score/confidence/signal density per entity. This goes beyond annotations to inform agent 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?

Three sentences with no waste: first states core function, second provides usage guidance with example, third describes output format. Front-loaded with key action and resource.

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

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

Given 4 parameters, active annotations, and no output schema, the description adequately prepares the agent by stating what is returned (ranked list with fields). It is complete enough for correct invocation and interpretation of results.

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

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

Schema coverage is 100% and provides basic descriptions. The description adds semantic value by noting the first entity is treated as the 'subject' for narrative purposes, which is not in the schema. This helps the agent understand parameter semantics beyond raw 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 compares AI visibility across multiple entities, using ai_visibility_check internally, and ranks results. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the AI-presence focus.

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 contexts use as competitive AI-marketing audits with an example question. It implies when not to use (single entity: ai_visibility_check) but does not explicitly state exclusions or alternatives for edge 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds essential behavioral details beyond annotations: partial failure handling (bundlephobia timeout, sources_failed), composite nature, specific return fields, and performance note (5-30s). No contradictions.

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

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

The description is lengthy but well-structured with front-loaded purpose and detailed behavior. Every sentence adds value, though slight conciseness improvement possible.

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 tool with no output schema, the description thoroughly covers return values, partial failures, ecosystem scope, and performance. It provides all necessary context for an agent to use 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?

Schema coverage is 100% with both parameters described. The description adds context: package accepts scoped names, version defaults to latest, and it explains return fields. This goes slightly beyond the schema, earning a 4.

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

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

The description clearly states it is a composite check for npm packages, combining deps.dev and bundlephobia data. It uses specific verbs like 'scan' and 'fans out', and distinguishes itself from sibling tools by its unique focus on npm dependency evaluation.

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 when to use it: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also notes ecosystem limitations and fallback options, providing clear usage context.

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

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

The description discloses technical details beyond annotations: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. No contradiction with annotations (all positive hints).

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

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

The description is concise (3 sentences) with key info first: purpose, then when to use, then technical details. 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?

Given no output schema, the description covers return format (passages with offsets and similarity scores). It also explains behavior, limits, and pairing with sibling tool. Complete for a search tool.

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

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

Schema covers all 3 parameters with descriptions. The description adds usage context: 'text' is the document, 'query' examples, 'limit' default value. Adds meaningful guidance beyond schema.

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

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

The description clearly states it performs semantic search inside a fetched record. It uses specific verb 'search within' and resource 'record', and distinguishes from siblings like ask_pipeworx_grounded by explaining its use case for pre-fetched text.

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

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

The description explicitly says to use when the record is too large for the prompt, and it pairs with the sibling ask_pipeworx_grounded. It implies when to use but doesn't explicitly state when not to use or list direct alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds that it returns lat/lon and links to arrivals tool. No contradictions; adds moderate context beyond annotations.

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

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

Single sentence with action verb and return fields. Front-loaded and efficient with 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?

No output schema, but description partially compensates by listing return fields. Does not mention result limits, ordering, or error handling. Adequate for a simple search tool but could be more 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 parameters are fully described in schema. The description adds no new parameter information beyond restating 'by name' for query.

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 'Search for stops/stations by name' and specifies the return fields (naptanId, modes, zone, lat/lon). It distinguishes from siblings by mentioning naptanId is used by the arrivals 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?

The description implies use when needing a naptanId for arrivals, but does not explicitly state when to use this tool versus alternatives or when not to use it. Lacks explicit 'when to use' and 'when not to use' guidance.

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

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

The description discloses all relevant behavioral traits: creation side effect, idempotency (implied by returning existing subscription?), and expectations (OAuth requirement). It explicitly notes SMS caps, webhook failure auto-disable, and phone verification, which are not covered by annotations. 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 information-dense but well-structured: purpose first, then requirements, then types, then delivery. Every sentence is informative, though it could be slightly more compact. However, the front-loading of key details compensates.

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 covers the return value ('Returns the new subscription id'). It fully explains all parameters, types, and delivery channels. It addresses edge cases (webhook auto-disable, verification). No missing essential information for a three-parameter 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 description adds substantial meaning beyond the input schema, which already has 100% coverage. It provides concrete examples for each subscription type's params, explains webhook signing details, and clarifies constraints like phone verification and rate limits. This aids proper parameter construction.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource, and explicitly mentions returning a subscription ID. It distinguishes itself from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation.

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 requirements: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' It lists supported subscription types with examples and details delivery channel constraints (SMS phone verification, 10/day cap, webhook auto-disable). This guides the agent on when and how to use the tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by detailing the return content: 'category-bucketed example questions... each with the exact tool + argument shape'. 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 relatively long but packed with highly relevant information, front-loading the purpose and usage. Every sentence contributes value (examples, usage instructions, return details). Minor brevity trade-off for completeness is acceptable.

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

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

Despite lacking an output schema, the description fully explains the return value (categorized example questions with tool call shapes) and covers all essential aspects: when to use, how to use, what to expect, and scope control. No gaps.

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

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

Schema provides 100% coverage with a description for the optional 'topic' parameter. The tool description adds additional context by listing example topic values ('finance', 'pharma', etc.) and explaining behavior when omitted (full spread), thus adding meaning beyond schema.

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

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

The description clearly identifies the tool as an onboarding entry point for querying what Pipeworx can do, listing specific verb+resource (suggest questions) and distinguishing it from siblings like 'ask_pipeworx' and 'discover_tools' by explaining it returns categorized example questions with tool calls.

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: 'FIRST when you do not yet know what Pipeworx can do', and implies when not to use: after you know what to ask. Also references alternatives like meta-tools and provides context for command varieties (full spread vs topic filter).

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

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

Discloses ownership enforcement and soft-delete (deactivation) beyond annotations. Annotations already indicate non-destructive and idempotent, but description adds meaningful context.

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

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

Two sentences, front-loaded with action and parameter, efficient without redundancy.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, constraints, and side effects adequately, including relation to 'recent_alerts'.

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 with clear description. Description only repeats 'by id', adding no new semantic value. 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?

Clear verb 'Cancel' and resource 'subscription by id'. Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicit ownership constraint ('you can only cancel your own subscriptions') and notes that deactivation preserves historical events via 'recent_alerts'. Lacks explicit when-not to use or alternatives.

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

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

Despite strong annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds substantial context: it explains the fast path for company financial claims with percent-delta math, the fallback grounded pipeline, the detailed verdict list, and critical caller semantics for 'could_not_verify' (with verification_error) and 'unsupported.' There is no contradiction between the description and 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 long but every sentence earns its place. It opens with invocation examples, quickly moves to purpose, then covers pipeline, return values, and error semantics. The structure is front-loaded with the core definition and uses bolded terms for emphasis, making it scannable without 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?

Given the lack of an output schema, the description fully explains return values (verdicts, evidence, reasoning) and error cases. It covers both processing paths and notes the tool replaces 4-6 sequential calls, which gives the agent a clear model of the tool's internal workflow and edge cases. This is complete for a tool of this complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The tool description enriches the claim parameter by providing natural-language trigger phrases and an example, and explains processing implications like 'exact percent-delta math' that affect tolerance_pct usage. It adds practical nuance beyond the schema, justifying a score above baseline.

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

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

The description specifies a clear verb+resource combination: 'natural-language claim verification against authoritative sources.' It distinguishes itself from siblings by focusing on fact-checking and outlining two distinct processing paths (SEC EDGAR/XBRL for company financials, grounded pipeline for other claims). The scope is precise and immediately recognizable.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies behavior for 'could_not_verify' versus 'unsupported,' giving exclusion criteria. This goes beyond vague guidance and directly tells when to invoke this tool versus alternatives.

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