Noaa Tides

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is to add behavioral context. The description adds the default model (Workers AI free), the BYO-key cost implication for Anthropic, and the exact return shape, which goes beyond the annotations and provides valuable operational detail.

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

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

Two sentences, front-loaded with the core purpose, then key details (default model, cost, return format) and use cases. Every sentence earns its place; 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?

Despite no output schema, the description fully covers the return format (per-model {score, confidence, signals, raw_response} + combined view) and risk context (cost). The tool's complexity is well addressed given the 4 parameters and sibling landscape.

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 meaning by specifying the default model for the 'models' parameter and clarifying that '_apiKey' is only needed to enable Anthropic calls and that the user pays directly for those. This enriches the parameter semantics.

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

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

The description uses a specific verb ('Probe') and resource ('one or more LLMs') and states exactly what it does: score visibility (0-100) per model. It clearly distinguishes from siblings like ask_pipeworx by emphasizing multi-model probing and visibility scoring, not answering questions.

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

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

The description provides clear context on when to use ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), but does not explicitly mention when NOT to use or name alternative tools. This is clear context without exclusions, earning a 4.

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

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

Annotations already establish read-only, open-world, idempotent, non-destructive behavior. The description adds valuable behavioral detail: it routes to internal tools, auto-fills arguments, returns structured answers with stable citation URIs, works on every tier, and makes one fast call. No contradiction with annotations.

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

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

The description is long but every sentence earns its place: dominant instruction is front-loaded, followed by domains, trigger phrases, examples, tier behavior, and alternatives. There is no filler or repetition that weakens its usefulness.

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

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

Despite having no output schema, the description conveys what the caller gets: a structured answer with pipeworx:// citation URIs. It also covers scope, examples, alternatives, and default usage, making it complete for an agent to select and call 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%: the schema documents 'question' and five aliases. The description reinforces the natural-language nature and gives question examples, but it does not add parameter-specific semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: it routes questions to one of 5,743 tools across verified sources and returns structured answers with pipeworx:// citation URIs. It also distinguishes itself from siblings ask_pipeworx_grounded and deep_research, making its role unambiguous.

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

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

It gives explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE for most questions'), trigger phrases ('what is', 'look up', 'find'), domain examples, and clear when-not-to-use alternatives ('Step up only when needed: ... ask_pipeworx_grounded; ... deep_research').

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive, which covers safety. The description goes further by disclosing that candidate routing improvements are enabled live during tests, that no candidate is currently active, that behavior currently matches ask_pipeworx exactly, and that this is a fully working router rather than a forwarding wrapper. This is substantial context beyond the annotations and contains no contradiction.

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

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

The description is four sentences with no filler. Each sentence contributes distinct value: the beta identity and scope, the current candidate state, the usage instruction, and the reassurance that it is a full router. The structure front-loads the core purpose and keeps supporting details tightly relevant.

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 as a universal router, the description supplies everything an agent needs to invoke it correctly: what it is, how it currently behaves, when to use it, how it relates to ask_pipeworx, and what not to assume about fallback. The lack of an output schema is compensated by the explicit statement that the response shape is identical to ask_pipeworx.

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 question parameter and all five aliases are fully documented in the input schema. The description only mentions 'same arguments' and adds no additional parameter-level meaning, so the baseline score of 3 applies.

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

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

The description opens with 'Beta version of ask_pipeworx: identical universal router' and specifies the same 5,743 tools, same arguments, and same response shape. This clearly identifies the tool's function and distinguishes it from the stable ask_pipeworx sibling while also differentiating it from ask_pipeworx_grounded by its experimental nature.

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

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

The description explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It gives a clear when-to-use condition and names the primary alternative, though it does not provide an explicit when-not-to-use list beyond the implications of 'beta.'

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses key behaviors: it costs an extra LLM call, extracts only from tool results, and can return explicit refusals with specific refusal_reason values. This is substantial added behavioral context.

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

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

The description is information-dense but every sentence earns its place: purpose, mechanism, return shape, refusal reasons, usage criteria, and cost tradeoff are all packed in without fluff. The front-loaded purpose sentence immediately orientates the agent.

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

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

With no output schema, the description fully explains both success and refusal return shapes, includes concrete refusal_reason enums, and covers the key operational context (extra LLM call, high-stakes use cases, casual-use alternative). Nothing essential is missing for correct 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?

The input schema already provides 100% coverage, documenting the primary 'question' parameter and all aliases. The description does not add new parameter-level meaning beyond emphasizing natural language questions, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode' for high-stakes reads, specifying that it extracts answers only from tool results and returns evidence. It also explicitly contrasts itself with ask_pipeworx, making its distinct role immediately apparent.

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

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

It explicitly states when to use this tool: 'whenever an answer will be quoted, cited, or acted on' and when not to: 'prefer ask_pipeworx for casual lookups.' It even names ask_pipeworx as the alternative, giving agents clear routing 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 goes well beyond read-only/idempotent annotations, disclosing resolver confidence gating, low-confidence short-circuit statuses, closed-market behavior, wide-spread tradeability flags, news fallback fields, and cancellation-rule risk. No contradiction with annotations.

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

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

The description is front-loaded with a one-sentence purpose and uses CAPS-section headers to organize dense content. It is long, but the length is justified by the tool's complexity; still not as tight as the best-case two-sentence examples.

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

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

With no output schema, the description fully specifies response shapes, resolver contract fields, parent-event partition data, status codes, and safety behaviors. It also covers edge cases like illiquid spreads and cancellation-rule risks, making it essentially self-contained.

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

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

Schema already provides full descriptions for all three params, including enums and defaults. The main description mostly restates accepted market input formats and does not add material new meaning to depth or include_raw semantics; examples of fan-out behavior are useful 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?

Opening sentence names the exact action: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It further specifies inputs, classification, fan-out, and output comparison, clearly distinguishing it from sibling data-retrieval tools.

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

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

Explicitly states use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides detailed fan-out examples. It does not explicitly contrast with sibling Polymarket tools (e.g., polymarket_arbitrage, polymarket_edges), so it falls just short of a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable context beyond these: it specifies data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/trials for drugs), mentions correct handling of off-calendar fiscal years, explains result sorting by primary metric, and notes return of paired data with citation URIs. This gives a clear picture of behavior, though it could mention data freshness or potential limitations.

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

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

The description is dense but every sentence adds value: example queries, usage preference, data source details, sorting logic, and return format. It is front-loaded with trigger phrases and avoids redundancy. The length is justified by the tool's complexity and two entity types.

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 absence of an output schema, the description sufficiently explains return values (paired data + citation URIs) and result ordering. It covers both entity types comprehensively and includes enough context for an agent to select and invoke the tool correctly, even without additional documentation.

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

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

Although the schema already describes both parameters, the description significantly enriches their meaning. For 'type', it details exactly which financial metrics are pulled for companies and which counts for drugs. For 'values', it provides format examples (tickers/CIKs vs drug names) and clarifies the 2–5 count. This goes well beyond the schema's descriptions.

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

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

The description clearly defines the tool as a side-by-side comparison of 2–5 companies or drugs in one parallel call, using explicit trigger phrases like 'X vs Y' and 'which is bigger.' It distinguishes itself from sequential single-pack lookups by stating it should be preferred for comparisons, making the purpose unmistakable.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance. It also specifies the two entity types and their data sources, and lists example queries that should trigger the tool, effectively differentiating it from alternative approaches.

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

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

Annotations already declare readOnlyHint and non-destructive, so the safety profile is known. The description adds behavioral context beyond the annotations: it specifies the data is observed, timestamped, and available in English or metric units, and explains the optional bin behavior for ADCP stations.

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 main action, and includes necessary optional details without redundancy. Every clause 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?

The tool is moderately complex with six parameters, but an output schema exists, so return values need not be explained. The description covers the core functionality, optional bin, units, and data nature, but omits time_zone and potential limitations. Overall it is adequate for a read-only data fetch.

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 explicitly explains 'bin' and 'units', and implicitly conveys station and date range through the main clause. However, it does not mention 'time_zone', and date/station formats are left to the schema examples. With 0% schema coverage, the description partially compensates but not fully.

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 fetches observed current speed and direction readings for a NOAA current station over a date range, with optional bin support for ADCP stations. It distinguishes itself from sibling tools like water_level and met_obs by specifying the resource and data type.

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

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

The description provides clear context for when to use the tool: for current station data over a date range, with optional bin for ADCP. It does not explicitly name alternatives, but the purpose is specific enough to imply its niche among similar observation tools.

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

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

The description adds minimal behavioral context beyond the annotations. It does not mention return format, pagination, or side effects, but the annotations already declare the tool as read-only, idempotent, and non-destructive. There is no contradiction, but the description does not add extra value regarding 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 very concise, consisting of a single short phrase. However, it is a sentence fragment lacking a verb and reads more like a title than a functional description. While there is no wasted text, the structure is under-specified and not well-formed for conveying behavior.

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

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

Despite having annotations and an output schema, the description does not explain what vertical datums are, how they relate to a station, or what the response contains. The domain concept is left undefined, making the tool difficult to use correctly for an agent unfamiliar with maritime or geodetic terminology.

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

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

The schema has one 'station' parameter with no description, and the description does not elaborate on its format or meaning beyond 'for a station.' The schema example provides a station ID, but with 0% schema coverage, the description should compensate for the missing parameter detail. It fails to do so, leaving semantics to inference.

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 'Vertical datums for a station' identifies the resource (vertical datums) and the context (station), but lacks an explicit verb like 'retrieves' or 'lists'. It differentiates from sibling tools by naming a specific resource, but the purpose remains ambiguous because it is a noun phrase rather than a clear action statement.

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

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

No usage guidance is provided. The description does not state when to use this tool versus alternatives such as water_level or station_metadata, nor does it mention exclusions or prerequisites. The agent is given no contextual cues to decide between this and sibling tools.

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

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

With readOnly/openWorld/idempotent annotations already covering the safety profile, the description still adds substantial behavioral context: not open-web, parallel routing, finding packet shape, never-invented gaps[], contradictions[], stable fetchable citations, hop fields, semantic excerpting, latency, and auth/paid-tier conditions. None of this contradicts 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 dense; every block adds operational value, and key auth/alternative guidance is front-loaded. It earns its length, though it is somewhat redundant with the schema on depth semantics and could be tightened.

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

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

No output schema exists, so the description carries the return-contract burden; it discharges it by specifying packet fields, gaps[], contradictions[], hop, citation_uri, and fetchability guarantees. It also covers auth, latency, paid tiers, and depth semantics, so nothing needed to call it correctly is missing.

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

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

The schema already covers both parameters at 100% with rich enum descriptions, so the baseline is 3. The description adds meaning by explaining depth behavior (standard re-angles gaps, thorough chases leads, multi-step questions resolve in one call) and by framing the question parameter as broad/multi-part, which takes it 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 states a specific verb and resource: grounded multi-source research across Pipeworx's structured data catalog, decomposing questions into facets and routing them in parallel. It explicitly distinguishes itself from open-web search and from ask_pipeworx, so an agent can tell it apart 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?

It gives explicit when-to-use and when-not-to-use guidance: best for broad/multi-part structured-data questions; use ask_pipeworx for single lookups and breaking/current-news topics; and if not signed in, ask_pipeworx works on every tier. This names alternatives and selection conditions clearly.

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

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

Annotations already declare readOnly/idempotent/non-destructive. The description adds concrete behavioral details: returns top-N tools with names, descriptions, and full input schemas, and that results are ready to call directly with no second lookup. It also instructs to call first, which is useful 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?

Four sentences, each with distinct value: purpose, usage/domains, return format, and priority. The domain list is long but relevant. 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 exists, so the description carries the return-value burden—it does so by specifying top-N results with names, descriptions, and full schemas. Combined with annotations and thorough schema, all key aspects (what, when, output, safety) are 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 covers all 6 parameters with descriptions and examples (100% coverage). The description adds semantic context by enumerating supported domains and clarifying that the query is a natural-language task description, plus the top-N behavior tied to limit. This goes slightly beyond schema text.

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 'Find tools by describing the data or task,' clearly stating a discovery/meta-tool purpose. It lists specific domains (SEC filings, FDA drugs, etc.), distinguishing it from the many domain-specific siblings. No tautology.

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

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

Explicitly instructs 'Use when you need to browse, search, look up, or discover what tools exist' and ends with 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives actionable usage context and differentiates from direct data-query tools.

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

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

Beyond the readOnly/openWorld/idempotent annotations, it discloses fallback behavior (GDELT→GNews), source sunset and soft-fail (USPTO), expected empty sections (FDA products for small-molecule-only companies), and that an empty section is a real 'no data', not a bug. This is rich behavioral context that annotations alone do not 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 dense and front-loaded with trigger phrases and the key 'ALWAYS PREFER' guidance. It is long, but the tool's multi-source complexity justifies much of that length; slight redundancy with schema parameter descriptions and the extensive source list prevent a 5.

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

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

Despite having no output schema, the description enumerates every returned section, explains source-specific expectations, covers fallback and failure semantics, and details all accepted input forms plus the private-company edge case. Nothing material needed to call the tool correctly is missing.

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

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

Schema coverage is 100%, and the description adds further meaning with concrete examples ('AAPL', '0000320193', 'Moderna'), clarification that type values are interchangeable, and explanation of resolved_from/resolved_to when a name is passed. It meaningfully extends the schema.

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

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

Description opens with explicit user intents ('Tell me about X', 'brief me on Tesla') and states it produces a 'full cross-source profile of a US public company in ONE parallel call.' It clearly differentiates this from single-pack lookups and positions it as the holistic profile tool among siblings like resolve_entity 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?

The description explicitly instructs to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also covers unsupported inputs by explaining that a private company returns resolved:false with a notes line, preventing misuse for non-public companies.

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

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

Annotations already declare destructiveHint: true and idempotentHint: true. The description adds minimal behavioral context beyond that, mostly restating the delete action and adding 'previously stored' and 'sensitive data' context, but doesn't disclose additional side effects or error conditions.

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

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

The description is three concise sentences, front-loaded with the action verb, and contains no redundant information. Every sentence earns its place.

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

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

With one parameter, rich annotations, and no output schema, the description sufficiently covers the tool's purpose, usage context, and related tools. No critical details are missing for an agent to select and invoke this tool.

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

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

Schema coverage is 100% with the key parameter described as 'Memory key to delete.' The description's 'by key' does not add semantic detail beyond the schema, so it merits the baseline score 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?

The description states 'Delete a previously stored memory by key' with a specific verb and resource, clearly distinguishing it from sibling tools like remember (store) and recall (retrieve). The action and target are unambiguous.

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

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

It explicitly lists usage scenarios: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names paired tools: 'Pair with remember and recall.' However, it lacks an explicit 'when not to use' statement, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral detail by explaining the process ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format') and the output type ('single text blob'). This goes beyond the annotations while remaining consistent with them.

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

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

The description is exactly two sentences, front-loaded with the core functionality and followed by practical use cases. Every sentence adds value, with no filler or repetition of schema details.

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

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

Despite having no output schema, the description explicitly states the output is a 'single text blob ready to drop at site-root/llms.txt', covering return value. It also explains the extraction behavior and provides use cases, making it fully self-contained for a simple two-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?

Schema description coverage is 100%, so the schema already fully documents both url and max_links. The description reinforces the url's purpose ('for any URL') but does not add new meaning to max_links beyond what the schema provides. Baseline of 3 is appropriate given the high schema coverage.

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

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

The description clearly states the tool's function with a specific verb ('Generate') and resource ('llms.txt file'). It also specifies the output format and location ('ready to drop at site-root/llms.txt'), distinguishing it from sibling tools like scan_competitor_ai_presence by focusing on file generation rather than analysis.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context for when to use the tool. However, it does not name alternatives or explicitly state when not to use it, so it lacks exclusions.

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

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

Annotations already declare this as read-only/idempotent, so the description doesn't need to restate safety. It adds value by disclosing the exact return fields and the scope ('caller's active subscriptions'), which is useful 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?

Two sentences cover purpose, output, and usage guidance. No wasted words; the most important information is front-loaded.

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

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

With simple schema, strong annotations, and no output schema, the description provides enough detail to understand the tool's behavior and output, including return fields. It is complete for the tool's simplicity.

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

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

Schema coverage is 100% for the single optional parameter include_inactive. The description does not add parameter-level detail, but the schema already fully explains the parameter, so baseline 3 is appropriate.

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

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

The description explicitly states the tool lists the caller's active subscriptions, using a specific verb and resource. It also lists the returned fields (id, type, params, etc.), which clearly distinguishes it from sibling tools like subscribe and unsubscribe.

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

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

The description provides clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies when to use it versus subscribe/unsubscribe, though it doesn't explicitly name the 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the date range scope and product constraint, plus the return format ('timestamped sensor readings'), but does not disclose date formatting, units semantics, or station ID requirements. With annotations in place, this is adequate but not exceptional.

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

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

A single, front-loaded sentence states the action, resource, scope, and product list, then adds a brief return-value note. No wasted words or irrelevant details.

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

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

Output schema and annotations cover return values and safety. The description captures the core purpose but omits details on optional parameters (units, time_zone) and parameter formats, which are relevant for correct invocation. Adequate for a simple fetch tool, but with gaps for full agent self-sufficiency.

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 only 17% (product has an enum description). The description adds the product list and implies date range, but does not explain station ID format, begin/end date format, units options, or time_zone semantics. Low schema coverage demands more compensation than provided.

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 'Fetch' with a clear resource 'meteorological observations from a NOAA station' and scope 'over a date range for a specific product'. It lists all product options, distinguishing it from sibling tools like water_level or currents that retrieve different data types.

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

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

Usage context is implied by the description: use when you need meteorological observations for a station/date/product. However, it does not explicitly mention when not to use it or name alternative tools, relying on the agent to infer from the product list and sibling names.

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

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

Discloses several behaviors not present in annotations: rate limiting ('Rate-limited to 5 per identifier per day'), billing ('Free; doesn't count against your tool-call quota'), and the claim_token lifecycle for filing without an account. Also notes that the team reads digests daily and signal affects roadmap, which sets expectations for response times.

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

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

The description is longer than average but front-loaded with a clear purpose. Every sentence earns its place: use cases, exclusions, token usage, rate limits, and quota impact. It could be tightened slightly (e.g., the 'Not sure?' sentence could be trimmed), but it remains well-structured and readable.

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 covers the full workflow: filing, retrieving via claim_token, and expected outcomes. It addresses edge cases (different MCP server), usage limits, and how to phrase feedback appropriately, making the tool self-contained and complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds operational meaning beyond the schema by explaining how claim_token works ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and by tying the type enum to real-world situations. It also clarifies that context is optional, reinforcing the schema.

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

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

The description opens with a clear statement of purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names specific use cases (bug, feature/data_gap, praise) and explicitly contrasts with unrelated MCP servers, distinguishing this tool from siblings like ask_pipeworx and discover_tools.

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

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

Provides explicit when-to-use guidance by enumerating valid input types and scenarios (wrong/stale data, missing tool, praise). It also states when NOT to use it ('if the tool came from a different MCP server... file it with that server instead') and how to avoid misuse by identifying Pipeworx tools by 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: no PII, derived from CF analytics-engine, cached 5min-1h depending on window. This goes beyond the structured annotations and provides a clear, non-contradictory behavioral profile.

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

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

The description is front-loaded with purpose and returns, then uses a numbered list for use cases, and finishes with data provenance and caching. No unnecessary words; every sentence contributes to understanding the tool.

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

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

Despite having no output schema and a simple one-parameter input, the description covers the return format (pack, tool, count), window semantics, caching, and privacy. It is complete enough for an agent to decide to call and interpret the result.

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?

One optional parameter (window) is fully described in the schema, plus the description adds semantic trade-offs: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This guides parameter selection beyond the bare enum values.

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 'Returns the top tools, top packs, and total call volume over a recent window,' identifying the exact resource and action. It distinguishes itself from siblings by framing the data as 'What other AI agents are calling on Pipeworx right now' and listing specific use cases.

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

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

Three explicit use cases are provided, e.g., 'discovering what data sources are hot for current events' and 'confirming a popular tool is the canonical choice.' This gives clear context for when to use it, but it does not explicitly name alternative tools or state when not to use it.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses rich behavioral details: monotonicity checks, partition-sum sums with >3pp deviation thresholds, Jaccard similarity requirement, placeholder filters, and fill-check behavior that prices signals against live CLOB depth and warns when realizable_edge_pp ≤ 0. It also states 'do not trade it' under those conditions. No contradictions with annotations.

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

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

The description is long (~300 words) but well-structured with distinct sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds value, but it could be slightly more concise by moving response fields to an output schema. It is front-loaded with the core purpose and call modes, so it remains efficient for a complex tool.

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

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

With no output schema, the description carries full responsibility for return values and does so thoroughly: it lists opportunities fields, partition_check fields, and fill_check fields (theoretical_edge_pp_at_book, realizable_edge_pp, thin_legs). It also provides concrete example inputs for event and topic. For a tool with two optional params and complex behavior, this is very 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?

Even though the schema already describes both parameters at 100% coverage, the description adds significant extra meaning: 'event' accepts a full URL or slug, walks child markets and checks date/threshold ordering; 'topic' searches related events and flattens markets, catching cross-event patterns. These clarifications go well beyond the schema's short descriptions.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from siblings like polymarket_edges by focusing on arbitrage via specific algorithmic checks, and describes distinct modes (trending_scan, event, topic).

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

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

The description provides explicit guidance: 'Call with NO args for a trending_scan... pass `event`... or `topic`...' It also recommends the event mode for a specific market, explains cross-event mode use cases, and directs users to polymarket_fill_risk for custom sizing, effectively naming an alternative tool.

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

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

The description extensively discloses behavioral traits beyond the annotations: it details the three response segments, the model families, the calculation of edge_pp_net, Kelly caps, 24h-move warnings, the placeholder-slug filter, partition overround handling, and the caching policy ('Cached 1h at the KV level keyed on all knobs'). It even explains why concentrated_longshot is 'rare-by-design' and why Fed bets are unreliable. The readOnlyHint is consistent with the read-only nature of scanning and ranking.

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

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

The description is extremely detailed and front-loaded with a clear purpose sentence. It is organized into logical sections (model families, knobs, response structure, diagnostics, caching), but it is verbose. Some details, such as per-sport alpha values and specific funnel counters, may be beyond what an agent needs for selection and invocation. However, given the tool's complexity, the thoroughness is largely justified.

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

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

With no output schema, the description fully compensates by explaining the response top-level fields (by_segment, fed_candidates, _diagnostics), what each opportunity carries (edge_pp_net, kelly_fraction, market.liquidity, etc.), and how to interpret empty segments via filter_skips. It also covers edge cases like stale markets and knob behavior, making it complete for an agent to understand both inputs and outputs.

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

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

While the schema covers 100% of parameters, the description adds crucial meaning beyond the structured definitions. It explains the 'TRADEABLE-EDGE KNOBS' in context, clarifies that min_partition_leg_kelly applies to per-leg Kelly because partition-level kelly_fraction_half is always 0, and relates slippage_pp to Polymarket's zero-fee but bid/ask spread reality. This is material information not present in the schema.

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

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

The description clearly states what the tool does: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It identifies the specific verb-environment ('scan ... and return opportunities') and the output structure. This distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker by focusing on Pipeworx divergence rather than cross-exchange arbitrage or historical tracking.

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 specifies the intended use case ('Built for "what should I bet on today"') and explains when to use tradeable-edge knobs (e.g., min_liquidity, max_spread_pp) and what they do. It also clarifies that Fed bets are excluded from ranking and why, guiding users on interpretation. However, it does not explicitly name alternative tools or state 'when not to use this tool,' so it falls short of full 5.

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

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

Despite strong annotations (readOnly, openWorld, idempotent), the description adds substantial behavioral detail: snapshots are written on cache-miss, gaps indicate no scan, history limited by 60-day TTL, decay computed from daily closes not intraday. This goes far beyond the annotations and fully discloses operational constraints.

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

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

The description is long but well-structured: purpose, args, response format, and limits are clearly separated. It's front-loaded with the core purpose. Slightly verbose but every sentence earns its place given the lack of an output schema.

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

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

With no output schema, the description fully explains the response structure (tracked[], expired[], snapshot_dates[]) and key metrics (trend, decay_pp_per_day, lifespan_days). It also covers edge cases like snapshot gaps and TTL bounds, making it highly complete for a read-only telemetry tool.

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

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

Schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds only minor context (e.g., 'lookback' synonym, 'snapshot family'), not significant new meaning. It also omits the min-2 clamp mentioned in the schema, but doesn't contradict it.

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

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

The description explicitly states it provides 'edge persistence and decay telemetry' built from snapshots, clearly distinguishing it from sibling tools like polymarket_edges which likely show current edges. It names a specific verb ('answers how long has this edge existed') and resource (daily snapshots), making it unmistakable.

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

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

It gives a concrete use case: 'a fresh wide edge and a 3-week-old wide edge are different trades,' implying when to use this tool for historical context. It does not explicitly name alternatives or exclusions, but the context is clear and the source relationship to polymarket_edges is stated.

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

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

Even though annotations already declare read-only, open-world, idempotent, and non-destructive behavior, the description adds significant detail: it walks the order-book ladder, returns specific fields for each mode, and warns about forced directional risk in basket mode. The description also notes the requirement to pass exactly one of market or event, and explains how size_usd is interpreted differently depending on mode.

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

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

The description is long but densely packed. It uses clear structural markers (SINGLE-MARKET, BASKET) and every sentence adds essential information. Given the tool's two modes, many output fields, and nuanced risk rationale, the length is justified and well-organized.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly for both modes (lists all key fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, theoretical_sum vs realizable_sum, capture_ratio, etc.). It also covers parameters, defaults, and usage context, making the tool fully understandable without supplemental documentation.

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

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

While the schema covers all parameters, the description enriches them by explaining the meaning of side in both modes (e.g., default auto for basket), the interpretation of size_usd (max spend vs. target proceeds vs. settlement notional), and the required mutual exclusivity of market and event. It adds practical context beyond the schema definitions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It specifies two distinct modes (single-market and basket), names the exact output metrics, and distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk rather than opportunity detection.

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

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

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' The description explains why this tool is necessary (theoretical overround on thin books is not capturable) and highlights the risk of partial basket fills, giving clear before-when and rationale.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description adds substantial beyond-annotation context: token-overlap matching, compatibility codes, unknown legs never being paired, null temporal fields, skipped counters, and the gross-vs-net fee caveat. This is especially valuable because it prevents an agent from misreading spread values as net tradeable edges.

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

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

The description is long but dense, with each section carrying distinct decision-relevant information: modes, response anatomy, safety fields, codes, fee treatment, and dropped comparisons. The core definition is front-loaded, and the length is justified by the tool's complexity, though section breaks would improve readability.

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

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

For a complex tool with no output schema, the description covers return fields, flag semantics, null meanings, matching limitations, and fee caveats. An agent has enough context to invoke both modes correctly and interpret responses accurately, including edge cases like unclassified legs and temporal ambiguity.

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 each parameter is already documented. The description adds meaning beyond the schema by explaining the relationship between topic and the two override parameters, and by clarifying that both modes run the same matcher. This lifts it above the baseline while not being strictly necessary for invocation.

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

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

The opening sentence states a specific function: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes this tool from same-venue edge tools by emphasizing the cross-venue scope and matching logic. The two modes and response scope further pin down exactly what the tool does.

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

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

The description gives explicit decision guidance for TWO MODES: using 10 pre-mapped topics versus supplying explicit ticker/slug pairings. It also warns that pre-mapped topics often return compatibility warnings and are not automatically tradeable. It does not name a specific sibling alternative, but the mode-based selection guidance is clear enough.

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

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

The annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which cover safety. However, the description adds no behavioral context beyond that, such as requiring a date range, time zone handling, or output structure. It neither contradicts annotations nor adds meaningful transparency.

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

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

The description is under-specified—two words cannot convey enough information. It is concise but at the expense of clarity, resembling a title rather than a tool description.

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

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

Given 7 parameters and an output schema, this minimal description is grossly incomplete. It doesn't explain the tool's core function, usage context, or any operational nuances, making it inadequate for an agent to correctly invoke the tool.

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

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

The description offers no parameter information. With 57% schema coverage, the undocumented parameters (station, begin_date, end_date) are not clarified. The description fails to compensate for the moderate schema coverage, so an agent gets no extra meaning.

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

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

The description 'Tide predictions' is a noun phrase that essentially restates the tool name with a domain qualifier. It lacks a verb or action, so it doesn't clearly state what the tool does (e.g., 'Get tide predictions for a station and date range'). It provides only vague differentiation from siblings like water_level or currents.

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

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

There is no guidance on when to use this tool versus alternatives. The description doesn't mention prerequisites, typical scenarios, or exclusions, leaving the agent without context to select this tool from the large sibling list.

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

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

Annotations already mark readOnly, idempotent, non-destructive. The description adds useful behavioral context: scoping to identifier and list-all-keys behavior, but does not describe return format or missing-key error behavior, so it stays at baseline 3.

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 tightly written sentences; the first front-loads the operation, the second explains the use case, the third adds scoping and sibling pairing. No filler.

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

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

For a simple, single-optional-param read tool with strong annotations and high schema coverage, the description covers purpose, usage, scoping, and related tools sufficiently; no return-format details are necessary here.

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 the only parameter thoroughly ('Memory key to retrieve (omit to list all keys)'). Description reinforces omit behavior and gives example values (e.g., user's target ticker, address), providing modest extra semantics 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?

Description opens with 'Retrieve a value previously saved via remember, or list all saved keys' – a specific verb and resource, and the optional-key behavior distinguishes it from remember/forget siblings.

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 frames when to use: 'to look up context the agent stored earlier... without re-deriving it from scratch', and names complementary tools ('Pair with remember to save, forget to delete'). It lacks an explicit when-not/alternative list, so not a 5.

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

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

The description discloses the mark_read:true side effect ('flag returned events read so the next call only shows newer ones'), which implies a state mutation. This directly contradicts the annotation readOnlyHint:true. Per the rubric, any contradiction between description and annotations mandates a score of 1 and flags annotation_contradiction=true.

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 five short sentences, front-loaded with the primary action in the first sentence. Every sentence adds unique value: core function, return payload, filtering, mark_read side effect, and alternative access. No fluff or redundancy.

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

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

With no output schema, the description compensates by listing return fields (source, citation_uri, raw event payload). It also covers filtering options, the read-state mechanism, and provides an alternative access method. All five parameters are represented either in the schema or the description. The description is substantially complete for a read-oriented feed tool.

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

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

Schema coverage is 100% with descriptions for every parameter. The description adds value beyond the schema by giving a concrete type example ("sec_8k") and clarifying that `since` takes an ISO timestamp. It also explains the behavioral consequence of mark_read:true, which is not in the schema. 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?

The description opens with 'Pull fired events from your subscription feed', which is a specific verb+resource combination. It clearly distinguishes itself from siblings like list_subscriptions (which lists subscriptions) and subscribe/unsubscribe by focusing on the fired event feed.

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

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

The description provides usage context by explaining that polls work fine and that the same feed is available at a direct URL for scripts/dashboards, implying this tool is for interactive use. It does not explicitly exclude alternatives among sibling tools, but the context is clear enough for an agent to decide when to use it.

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

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

Beyond the readOnlyHint, it discloses the parallel fan-out to three sources, the GDELT→GNews fallback on rate limits/5xx, and the USPTO soft-fail due to PatentsView API sunset. These are non-obvious behaviors an agent needs to set expectations.

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

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

Every sentence delivers value: query examples, source list, fallback, parameter syntax, return format, and cross-reference. No fluff or redundancy—compact yet comprehensive.

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

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

With no output schema, the description appropriately explains the return shape (changes[] grouped by source, total_changes count, pipeworx:// citation URIs). It also covers parameter formats, source expectations, and an alternative tool, making it fully self-contained for an agent.

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

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

Schema coverage is 100% so baseline is 3, but the description adds practical guidance: 'since accepts ISO date or relative shorthand' with examples, and recommends '30d' or '1m' for typical monitoring. This goes beyond the schema's dry type declarations.

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

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

The description clearly states this is a 'change feed for a company in the last N days/weeks/months in ONE parallel call' and lists specific sources (SEC EDGAR, GDELT/GNews, USPTO). It also differentiates from sibling tool entity_profile by name, making the purpose unmistakable.

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

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

It opens with concrete user query examples ('What's new with X'), explains the multi-source fan-out with fallback behavior, and explicitly directs users to entity_profile for static profile needs. This provides strong when-to-use and alternative guidance.

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

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

Annotations indicate non-read-only, idempotent, and non-destructive behavior. The description enriches this with important context: memory is scoped by identifier, authenticated sessions persist, anonymous sessions expire after 24 hours. No contradiction with annotations, and the added retention semantics exceed what annotations convey.

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

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

Three sentences, each earning its place: what it does, when to use it, and how it behaves. Front-loaded with the core purpose, no wasted words.

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

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

For a simple two-parameter write tool, the description covers purpose, usage timing, persistence semantics, and companion tools. No output schema is required, and the description does not need to explain return values. All essential context 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?

The schema already documents both parameters with examples (100% coverage). The description reinforces the key-value model and provides domain-specific examples of keys and values, adding contextual meaning beyond the schema's generic 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: 'Save data the agent will need to reuse later' — a specific verb and object. It explicitly frames the resource as a key-value pair and distinguishes itself from sibling tools by naming recall and forget as companions.

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

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

Provides explicit when-to-use guidance with concrete examples: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject)'. Also directs to alternatives: 'Pair with recall to retrieve later, forget to delete.'

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

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

The description goes well beyond the annotations by disclosing graceful degradation ('LEI/FIGI enrichment degrades gracefully'), ambiguity handling ('returns `figi_candidates` to pick from'), explicit failure reporting ('stated explicitly under `unresolved` rather than omitted'), and internal cascading lookups. These are meaningful behavioral traits an agent would not know from the schema or 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 it front-loads usage examples and the 'Use FIRST' directive. Most sentences carry operational value, though the single giant block of parentheticals makes it harder to scan. It is more verbose than ideal but 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?

Given the tool's complexity, two required parameters, and absence of an output schema, the description is unusually complete. It explains what identifiers are returned, how ambiguity is handled, what happens on partial failure, and what input forms are accepted. An agent has enough context to call 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?

The input schema already covers both parameters at 100%, but the description adds critical semantic nuance: accepted input formats include ISIN, the 'ENTITY NAME ONLY' rule with a bond-specific example, and the distinction between accepted identifier types. This materially improves the agent's ability to construct correct parameter values.

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

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

The description opens with concrete user phrasings and states a precise purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly delineates supported types ('company', 'drug') and the identifier families returned, making it easy to distinguish from sibling tools like entity_profile or 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?

The description explicitly says 'Use FIRST whenever you have a name but need an ID' and provides recognizable triggers ('what's the ticker for…', 'find the CIK for…', 'who owns X', 'is X a subsidiary of Y'). It does not explicitly name alternatives to avoid, so it stops short of full when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description needn't cover side effects. It adds process details (probes each entity, ranks by score) but does not disclose that it makes multiple external API calls per probe, which could have latency or cost implications.

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: purpose, process, use case, and return value. Every sentence earns its place with no redundancy or filler.

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

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

Despite having no output schema, the description clearly states the return format (ranked list with score, confidence, signal density). It also contextualizes the operation by naming the underlying ai_visibility_check tool. It could mention rate limits or external model probing, but that is not essential.

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 covers 100% of parameters, providing a baseline of 3. The description adds meaningful semantics by explaining that the first entity in 'entities' is the 'subject' and the rest are competitors, which directly impacts the narrative and ranking output.

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 'Compare AI visibility across multiple entities side-by-side', providing a specific verb and resource. It distinguishes itself from sibling ai_visibility_check by explicitly saying it probes that tool for each entity and ranks results, making its purpose unambiguous.

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

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

The description offers a concrete use case: 'Useful for competitive AI-marketing audits' with an example query. It implies that for single-entity checks one would use ai_visibility_check instead, but does not explicitly name alternatives or exclusions.

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

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

Annotations declare read-only, idempotent, open-world. The description adds significant behavioral context: partial failure degradation, bundlephobia's first measurement can take 5-30s, and the sources_failed field will list timeouts. This exceeds what annotations provide and helps the agent set expectations.

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

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

The description is dense but every sentence delivers value: core purpose, when to use, output fields, ecosystem limitation, and failure behavior. It is well-structured with em-dashes and clear separation of concerns, appropriately sized for the tool's complexity.

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

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

Without an output schema, the description carries the burden of explaining return values, and it does so comprehensively: summary block fields, per-advisory detail, links, alternative versions. It also covers limitations (npm only) and failure modes, making the tool fully self-explanatory.

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

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

Schema description coverage is 100%, with both package and version fully described. The tool description does not add additional parameter semantics or examples beyond the schema, so it meets the baseline but does not go further.

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

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

The description clearly states the tool's purpose: a composite check for adding an npm package, fanning out to deps.dev and bundlephobia. It specifies the exact data returned (license, advisories, bundle size, etc.) and distinguishes itself from sibling tools by its specific scope and data sources.

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 tells when to use it: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an alternative for other ecosystems: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly'.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral detail beyond that: the embedding model (BGE-base-en), cosine similarity over 500-char overlapping windows, the 200K char cap with truncation flagging, and the output structure (character offsets, similarity scores). It also notes 'every passage carries an offset so the agent can verify a verbatim quote,' which is extra transparency about output verifiability. 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 five sentences, each earning its place: the core action, the input/output contract, the primary use case, the sibling pairing, and the technical embedding/limit details. It is front-loaded with the most important information and avoids redundancy with the schema. 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 appropriately explains the return values (top-N passages with character offsets and similarity scores). It covers the complete workflow, including the input source, the query, the limit default (mentioned in schema), the max text size, truncation behavior, and the companion tool. For a search tool with three simple parameters, this description is fully sufficient 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 description coverage is 100%, so the baseline is 3. The description adds contextual meaning beyond the schema: it clarifies that 'text' is the previously fetched record (e.g., SEC 10-K body), that 'query' is a natural-language request with examples, and it reinforces the limit's purpose with 'top-N passages.' The description also mentions the 'truncated and flagged' behavior tied to the text cap, which enriches the parameter semantics beyond raw schema constraints.

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

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

The description opens with a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes itself from siblings by emphasizing that it operates on already-fetched text, and it explicitly differentiates from ask_pipeworx_grounded by framing this as the passage-level search companion. The purpose is unambiguous and not tautological.

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 states exactly when to use this tool: 'Use when the record is too big to cram into the prompt.' It explicitly names the alternative workflow with ask_pipeworx_grounded, explaining how to fetch with the gateway and then ground over relevant passages. This is clear, actionable guidance and gives an exclusion (when you don't need full-text grounding).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the constraint that the ID must be numeric and the content categories, but it does not disclose additional behavior such as error responses, rate limits, or data freshness. Given the annotations, the description provides modest but acceptable value.

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 immediately states the action and resource. Every phrase contributes value: 'full metadata', 'numeric station ID', and the content list. There is no redundancy or filler.

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

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

With only one parameter, an output schema present, and safe/idempotent annotations, the description covers all essential aspects for correct invocation. It explains the required input format and what to expect in the output (location, products, status). No further guidance is necessary given the tool's simplicity and the presence of an output schema.

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

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

The input schema has 0% description coverage for the parameter 'station', but the description adds important semantic detail by specifying that the ID is numeric and giving an example (8454000). This compensates for the schema's lack of field description, although the example is repeated from the schema. The description effectively clarifies the expected input format.

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 function with a specific verb ('Fetch'), a specific resource ('full metadata for a single NOAA station'), and the input format ('numeric station ID'). It also lists the metadata content (location, available products, operational status), distinguishing it from the sibling 'stations' tool which likely lists multiple stations.

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

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

The description provides clear context for when to use the tool: when you need full metadata for one specific station by numeric ID. It does not explicitly name alternative tools or state when not to use it, but the 'single station' qualifier implicitly separates it from listing tools like 'stations'. This meets the bar for 'clear context, no exclusions'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile. The description adds value by specifying return contents (station IDs, names, coordinates) and the filter behavior (by type). It does not mention pagination or potential performance characteristics, but given the strong annotation coverage, the added details are sufficient.

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

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

The description is a single, front-loaded sentence that communicates purpose, filtering, and return values with no wasted words. It is concise, efficient, and well structured for quick parsing by 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?

For a simple listing tool with two optional parameters, complete schema descriptions, an output schema present, and strong annotations, the description fully covers the essential context: what the tool does, what it returns, and how to filter. No significant gaps remain; the output schema handles return structure details, so the description need not repeat them.

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%—both 'type' and 'format' have descriptions in the schema. The description repeats the filter options and says 'List all', which adds little beyond the schema. Since the schema fully documents the parameters, a baseline of 3 is appropriate; the description does not introduce new semantic details.

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

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

The description uses a specific verb ('List') and resource ('NOAA Tides & Currents monitoring stations'), and clearly distinguishes from siblings like currents, water_level, and station_metadata by focusing on station discovery. It also names the filter types (waterlevels, currents, physical, meteorological) and return content (IDs, names, coordinates), making the tool's role unmistakable.

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

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

The description implies usage as a discovery tool ('List all stations; filter by type') and mentions 'Returns station IDs, names, and geographic coordinates', which suggests a precursor to data-retrieval tools. However, it does not explicitly mention alternatives or when to prefer station_metadata or current/water-level tools. No exclusions or when-not-to-use guidance is provided.

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

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

Annotations already indicate readOnly=false, idempotent=true, and openWorld=true. The description adds valuable behavioral context: auth requirements, feed always-on behavior, sms verification and rate cap, and the fact that the subscription id is returned. It does not mention idempotency explicitly but does not contradict the annotation either. Given annotation coverage, this adds a solid layer of behavioral detail beyond structured fields.

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

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

The description is long but every sentence contributes meaningful detail. It is structured logically: purpose/return value, prerequisites, supported types with examples, and delivery channels. Though it could be trimmed slightly (e.g., webhook details are left to schema), the density is justified given the tool's complexity and multi-type nature.

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

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

Given there is no output schema, the description appropriately mentions the returned subscription id. It covers the main success paths (create, delivery), prerequisites, and rate limits. The webhook channel is only described in the schema, not the description, but that's acceptable since the schema covers it. For a tool with nested objects and multiple subscription types, the description is sufficiently complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description enriches semantics by providing concrete examples like items:["5.02"] = officer change and clarifying delivery channel requirements (verified phone, 10/day cap). This goes beyond the schema's parameter descriptions, which are already detailed, offering additional actionable nuance.

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

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

The description opens with a specific verb+resource ('Create a proactive monitoring subscription to a live-data event stream') and clearly distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on the creation act. It further specifies supported subscription types and return value, making the tool's purpose unmistakable.

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

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

The description provides clear context: when to use (for proactive monitoring), prerequisites (OAuth account required, anonymous/BYO cannot persist), and how to consume alerts via feed/email/sms. However, it does not explicitly name alternatives like 'use list_subscriptions to view existing subscriptions' or 'use unsubscribe to cancel,' so it lacks explicit exclusions or alternative references.

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

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

Annotations already establish safety (readOnlyHint, idempotentHint, non-destructive), and the description goes well beyond that by disclosing output structure (category-bucketed questions with tool+argument shape), dynamic source ('drawn from the live catalog of thousands of tools'), and invocation behavior (no-arg vs topic). 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 dense but well-organized: it front-loads common queries and the core purpose, then covers output content, invocation variants, and when to use the tool. Every sentence contributes—no filler or redundancy.

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

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

Even though there is no output schema, the description adequately explains what the tool returns: category-bucketed example questions with tool+argument shapes, plus a list of categories. It lacks explicit error handling or invalid-topic behavior, but for a simple onboarding tool the description is substantially complete.

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

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

The schema already documents the `topic` parameter with allowed values and 'Omit for a cross-category spread.' The description adds concrete examples ('finance', 'pharma', 'betting') and reinforces the semantics of 'full spread' versus focused topics, which slightly exceeds the schema's bare enum list.

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

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

The description explicitly states this is the 'onboarding entry point' and 'returns category-bucketed example questions' with 'the exact tool + argument shape' for each. It clearly distinguishes itself from siblings by saying 'Use this FIRST when you do not yet know what Pipeworx can do.'

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

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

The description gives explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains two invocation styles—'Call with no arguments for the full spread, or pass `topic`.' However, it does not explicitly say when NOT to use it or name an alternative tool, so it lacks full exclusionary guidance.

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

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

Beyond the annotations (readOnly=false, idempotent=true, destructive=false), the description adds key behavioral details: ownership enforcement and that the row is deactivated rather than deleted, preserving historical events via recent_alerts. This is valuable 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 two sentences, front-loaded with the action, and every sentence adds 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?

For a simple tool with one parameter and no output schema, the description covers the core action, ownership restriction, and deactivation semantics. It doesn't mention error cases, but that's acceptable for this level of complexity.

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

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

Schema coverage is 100%, with the id parameter already described as 'Subscription id (uuid) returned by subscribe.' The description merely repeats 'by id' without adding further parameter semantics, so baseline 3 applies.

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

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

The description states exactly what the tool does: 'Cancel a subscription by id.' It uses a specific verb and resource, and clearly differentiates from siblings like 'subscribe' and 'recent_alerts' by explaining the cancellation and its effect on historical events.

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

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

The description provides clear usage context: ownership is enforced ('you can only cancel your own subscriptions'), and it notes the deactivation behavior. While it doesn't explicitly list alternatives, these constraints imply when it's appropriate to use.

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

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

Goes well beyond the readOnly/idempotent annotations by detailing the two routing paths, the exact verdict values, the semantics of could_not_verify (with verification_error structure) versus unsupported, and a critical caller warning not to present could_not_verify as evidence. This is rich behavioral disclosure that fully answers the 'how does it behave' question.

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 carries purpose—starting with user-intent examples, then the core directive, then routing details, return shape, and an important caller caveat. No redundancy; it is front-loaded and well-structured for a tool of this complexity.

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

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

Given there is no output schema, the description thoroughly covers return values: verdict options, actual value with citation, reasoning, and the verification_error structure. It also explains both parameter behaviors and error semantics, leaving minimal ambiguity about invocation and 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?

While the schema already covers both parameters (100% coverage), the description adds meaningful semantic guidance for tolerance_pct: it overrides the implied wording tolerance, defaults to a cap of 5, and recommends 1–2 for hallucination detection. This enriches understanding beyond the 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 does natural-language claim verification against authoritative sources, using phrases like 'fact check' and 'verify the claim that...'. It distinguishes itself from sibling tools by detailing the two execution paths (SEC EDGAR fast path vs. grounded pipeline) and by noting it replaces 4–6 sequential calls, making its specific role unmistakable.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains when each code path applies (company-financial vs. other claims). It also advises on the meaning of could_not_verify, but does not explicitly name alternative tools or state exclusions, so it falls short of a 5.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful context: readings are observed/verified, referenced to a tidal datum, and returned as timestamped water-height values. This is consistent with annotations and enriches the tool's behavioral profile.

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

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

The description is two sentences with no filler. It front-loads the verb and resource, then adds essential format and output details efficiently.

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 6 parameters and no schema descriptions, the description covers most key aspects: data type, station, date range, datum, units, and output. An output schema exists, so return values don't need elaboration. The only gap is the time_zone parameter, but overall it is sufficiently complete for practical use.

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 0%, so the description carries the burden. It explains station, begin/end date format, datum default, and units. However, time_zone is not mentioned, leaving that parameter's semantics to be inferred from its name.

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 exactly what the tool does: fetch observed (verified) water level readings for a NOAA station over a date range. It distinguishes from sibling tools like predictions and currents by explicitly saying 'observed (verified)' and by focusing on water level data for a station.

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

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

The description provides clear usage context: date format (YYYYMMDD), datum default (MLLW), and unit options (english/metric). It implies when to use – for observed, verified water level readings – but does not explicitly name alternatives or exclusions.

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