Boe Uk

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the tool is known to be safe. The description adds valuable behavioral context: default model is free (Workers AI), passing _apiKey to also probe Anthropic means 'BYO key — you pay Anthropic directly for those calls', and it details the return structure (per-model score, confidence, signals, raw_response + combined view). This goes beyond the annotations.

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

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

The description is three sentences, front-loaded with the core purpose, and each sentence adds distinct value: functionality, configuration/cost, and use cases. No wasted words; the formatting is clean and scannable.

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

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

With no output schema, the description compensates by specifying the return format (per-model score, confidence, signals, raw_response + combined view). It also covers key operational details (default model, API key requirement, cost) and typical use cases. It doesn't address edge cases or errors, but for a moderate tool with full schema coverage, this is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the 'models' parameter values ('workers-ai' free default, 'anthropic' requires _apiKey) and clarifies the _apiKey behavior ('Passed straight through to api.anthropic.com'). This helps the agent understand parameter interdependencies beyond the schema.

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

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

The description clearly states the tool's function: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' The verb 'probe' and specific output ('score visibility') make it distinct. It also differentiates from siblings like 'scan_competitor_ai_presence' by focusing on multi-model probing and explicit scoring.

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

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

The description provides concrete use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' This gives clear context for when to use the tool, though it doesn't explicitly name alternative tools or when not to use it. The practical scenarios are enough to guide an agent.

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 safety traits are covered. The description adds substantial behavioral context beyond those: it routes to 5,334 tools across 1,393 sources, fills arguments, returns stable pipeworx:// citation URIs, works on every tier, and is one fast call. It does not mention error cases or rate limits, but for a read-only, idempotent lookup tool, the additional routing/citation behavior is valuable and non-contradictory.

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

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

The description is relatively long but front-loaded with the most critical instruction ('PREFER OVER WEB SEARCH') and organized into clear usage phases. Every sentence adds value: examples, alternatives, and scope. There is minor redundancy between 'PREFER OVER WEB SEARCH' and 'START HERE', but the density is appropriate for a meta-tool that needs to convey routing behavior and alternatives.

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

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

This tool has no output schema, so the burden is on the description to explain return values, which it does: 'returns the structured answer with stable pipeworx:// citation URIs'. It also covers the full input range, the breadth of data sources, the use of aliases, examples, and clear differentiation from alternatives. For a tool of this complexity (6 schema params, no output schema), the description is exceptionally complete.

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

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

The input schema already documents all six parameters, with five aliases clearly described and the 'question' parameter defined as natural language. Schema coverage is 100%, so the description's additional examples ('current US unemployment rate', 'Apple's latest 10-K') add helpful illustration but do not introduce new parameter semantics. This falls at the baseline 3 for high schema coverage.

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

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

The description clearly states the tool's function with a specific verb: it routes factual questions to the right source tool and returns structured answers with citations. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, and identifies its scope ('current or historical data... SEC filings, FDA drug data, FRED/BLS...'). This is a specific, value-rich description that leaves no doubt about 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 provides explicit usage guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and names alternatives with specific use cases ('use ask_pipeworx_grounded for a hallucination-resistant single answer', 'deep_research for broad/multi-part questions'). It also clarifies when not to use it (breaking-news already handled). This is a model of when-to-use/when-not-to-use instruction.

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 annotations by disclosing the beta status, the lack of an active candidate (thus current identical behavior to ask_pipeworx), the possibility of candidate routing improvements, and the fact that it is a fully functional router with no fallback. This gives the agent a precise behavioral model for an experimental tool.

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 long and every sentence contributes meaningful context: beta nature, current equivalence, usage directive, comparison purpose, and full functionality. It is slightly verbose but well-structured and not repetitive, earning a 4.

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

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

Given the tool's complexity (a router with thousands of tools) and the absence of an output schema, the description covers purpose, usage, behavior, current state, and guarantees. It references ask_pipeworx for response shape, which is helpful, though it could have provided a bit more detail on what 'routing' means in practice. Still, it is reasonably complete.

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

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

The input schema has 100% coverage with all six parameters described (including aliases). The description adds no additional parameter-specific information beyond saying 'same arguments' as ask_pipeworx, which is redundant with the schema. Baseline 3 is appropriate since the schema fully documents the parameters.

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

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

The description clearly states this is a 'Beta version of ask_pipeworx' and a 'universal router' with the same 5,334 tools, arguments, and response shape. It explicitly distinguishes itself from the stable ask_pipeworx by being the experimental candidate edge, so the purpose is unambiguous and sibling-differentiated.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. This gives a clear when-to-use directive, though it does not explicitly list when not to use it or mention alternatives like ask_pipeworx_grounded. Still, the guidance is practical and scenario-based.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, but the description adds critical behavioral context: refusal reasons ('not_in_source', 'no_tool_match', etc.), the output shape, and the extra LLM call cost. No contradiction with annotations; this meaningfully goes beyond 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 dense but every sentence earns its place: purpose, routing mechanism, return contract, refusal semantics, usage guidance, and cost tradeoff. It is front-loaded with the core purpose and structured logically.

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

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

Since there is no output schema, the description fully specifies both success and failure return shapes, including refusal_reason enum values. It covers behavior, use cases, and tradeoffs, making it complete for an agent to invoke and interpret results correctly.

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

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

Schema description coverage is 100% with aliases for 'question' all documented. The description does not add additional parameter-level guidance beyond referring to the natural-language question. Since the schema already handles parameter definitions, baseline 3 is appropriate.

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

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

The description clearly states the tool's role: 'Hallucination-resistant answer mode for high-stakes reads.' It explains the mechanism (picks the right tool, extracts answer only from tool result) and distinguishes itself from ask_pipeworx by emphasizing extraction and refusal behavior.

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 when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and offers an alternative: 'prefer ask_pipeworx for casual lookups.' Also highlights the cost tradeoff of one extra LLM call, providing clear decision 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 cover read-only safety, and the description adds useful behavioral context: it returns the most recent observations first and implies a default of 10 via 'Latest N'. It does not mention update frequency or data format, but these are minor for such a simple tool.

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 concise sentence (18 words) that front-loads the key action and scope. No filler or redundant information.

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

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

For a simple time series tool with strong annotations and no output schema, the description covers the source, series ID, and ordering. However, it does not explicitly state the structure of each observation (e.g., date and value), which is a minor gap given no output schema exists.

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 'last' parameter described as 'Number of most-recent observations (default 10).' The description's 'Latest N observations' mirrors this without adding new semantics, so a baseline 3 is appropriate.

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

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

The description clearly states the tool returns the latest N observations of the Bank of England official Bank Rate, including the specific series ID (IUDBEDR) and ordering ('most recent first'). This is specific and distinguishes it from siblings like 'sonia' or 'get_series'.

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 context is clear: this tool is specifically for the Bank Rate series. It doesn't explicitly state when not to use it or point to alternatives, but given sibling tools like 'get_series' exist, the specificity is implied. No exclusions are needed for a simple data retrieval 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?

Beyond the readOnly/idempotent annotations, description discloses fan-out behavior, resolver confidence contract, low-confidence short-circuiting, closed-market handling, illiquid spread warnings, and cancellation-rule risk. This richly informs the agent of operational behavior without contradicting annotations.

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

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

The description is long but well-structured with clear section labels and examples; it front-loads the core purpose. Some redundancy exists (classifier list and multiple examples) but nearly every sentence adds operational detail.

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

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

Given no output schema, the description thoroughly documents response shapes, resolver contract, parent_event, news fields, safety statuses, and resolution-rule risk, covering edge cases an agent must know. Complete for this complex tool.

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

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

Schema covers all 3 parameters with descriptions (100% coverage). The description adds context about fan-out and response sizes but does not materially expand parameter meanings beyond the schema, meriting the baseline.

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

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

States 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' with a specific verb and resource. Lists input types and classifier categories, clearly distinguishing from other Polymarket/analysis tools in the sibling set.

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 intended use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides fan-out examples. Does not explicitly name alternative tools or when not to use, so 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 mark it read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: it retrieves latest 10-K data from SEC EDGAR/XBRL, handles off-calendar fiscal years, pulls FAERS counts for drugs, sorts results by primary metric, and returns paired data with citation URIs. 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 clause earns its place: trigger phrases, preference rule, type-specific behavior, fiscal-year edge case, sorting, return format, and efficiency benefit. It is front-loaded with the most important usage triggers before diving into details.

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

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

No output schema exists, so the description compensates by stating the return format (paired data + citation URIs) and ordering behavior. It also covers edge cases like off-calendar fiscal years and gives clear invocation guidance for both types. Complete for an agent to select and call 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%, but the description significantly enriches parameter meaning: it explains what type='company' vs type='drug' retrieves (revenue, net income, cash, debt vs FAERS counts, FDA approvals, trials) and clarifies the values array semantics with examples. This goes well beyond the schema's minimal 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 clear trigger phrases and states the core action: side-by-side comparison of 2–5 companies or drugs in one parallel call. It distinguishes itself from sibling tools like entity_profile by emphasizing multi-entity comparison and explicitly noting it replaces sequential lookups.

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

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

Provides explicit when-to-use guidance ('which is bigger / better', 'rank these companies', 'head to head') and states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This clearly directs the agent away from alternative single-entity lookups, satisfying the when/when-not criteria.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, but the description adds a wealth of behavioral detail: account and paid-tier requirements, parallel facet decomposition, findings packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), explicit gaps[] that are never invented, contradictions[] scanning, semantic excerpting of large records, and expected latency of 15-60s (up to ~90s for thorough). This goes far beyond annotation basics.

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 and well-organized: account requirement first, then core function, usage guidance, depth semantics, output details, and performance. Every sentence adds value, though a few concepts (e.g., gap recovery) are echoed in the schema's depth description, making it slightly redundant. Still, it front-loads critical constraints and remains highly structured.

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

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

With no output schema, the description carries the full burden of explaining the return format, and it does so comprehensively: findings packet, gaps[], contradictions[], hop field, citation_uri, and latency. Given the tool's complexity (parallel routing, multiple depth levels, account tiers), the description is fully sufficient for an agent to understand what happens before and after invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the 'depth' parameter with examples and clarifies the behavioral difference between standard and thorough (gap recovery and lead chasing), adding context beyond the schema's already thorough descriptions. It doesn't add syntax details, but the extra nuance justifies a small bump 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 clearly states the tool's verb and resource: 'Grounded multi-source research across Pipeworx's 1393 STRUCTURED data sources' in 'ONE call' and explicitly contrasts it with open-web search. It differentiates from siblings like ask_pipeworx, making the tool's unique role unambiguous.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' with examples, and explicitly says 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It even covers account prerequisites and fallback behavior, leaving no doubt about appropriate usage.

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

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

Annotations already indicate a safe read-only, idempotent operation. The description adds meaningful behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)', and emphasizes that each result is 'ready to call directly, no second schema lookup needed.' This goes beyond the annotations and clarifies output behavior. No contradiction exists.

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

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

The description is three sentences, each earning its place: purpose and scope, return format, and timing recommendation. The domain list is compact and informative, helping the agent understand valid use cases. 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?

With no output schema, the description carries the responsibility of explaining return values, and it does so clearly: top-N tools with names, descriptions, and full input schemas, ready to call. It also provides usage context and a clear call-first instruction, making it complete for a discovery tool despite its simple interface.

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

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

Schema coverage is 100% with detailed descriptions for every parameter, including aliases and examples. The description reinforces that the query is natural language and that limit controls top-N, but it adds no new parameter semantics beyond what the schema already provides. Baseline 3 is appropriate given the schema's thoroughness.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It specifies the resource (tools) and the action (find), and distinguishes this from other tools by detailing the return of tool metadata (names, descriptions, schemas) rather than direct data answers. The list of domains (SEC, financials, FDA, FRED, etc.) and the note to 'Call this FIRST' further differentiate it from sibling tools.

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

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

The description gives explicit when-to-use context: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It implies a when-not (when a specific answer is needed), but does not name alternative tools explicitly, 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?

Despite annotations already marking it read-only/idempotent, the description adds substantial context: fan-out across sources, the USPTO PatentsView sunset with soft-fail behavior, GDELT→GNews fallback, and exact return fields like pipeworx URIs. No contradictions with annotations.

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

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

The description is long but information-dense, with a front-loaded example list and a structured return-value breakdown. Slightly run-on but each clause earns its place for a multi-source tool.

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

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

For a complex cross-source tool with no output schema, the description lists all return categories (cik, filings, fundamentals, patents, news, LEI) and specific field names. It also covers input constraints, fallback behavior, and the soft-fail condition, making it complete for an agent to invoke correctly.

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

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

Schema already covers both parameters at 100%, but the description adds meaningful examples (AAPL, 0000320193), clarifies zero-padding, and reinforces that names are not supported. This goes beyond the schema 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 concrete user examples then states 'full cross-source profile of a US public company in ONE parallel call,' clearly specifying the verb, resource, and scope. It distinguishes itself from single-source lookups and names resolve_entity for name-only inputs.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and provides the alternative resolve_entity for names. It also lists supported input formats and warns against unsupported names.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral context by stating the observations are most recent first and specifying the series code, which helps the agent understand the data ordering and source. This goes beyond the annotation-provided safety profile.

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

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

The description is a single, concise sentence that front-loads the core functionality, includes the currency pair, unit, series code, and ordering. There is no redundant information or filler.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is reasonably complete. It specifies the type of data (spot rate), the series, the ordering, and the unit. It does not detail the exact return structure, but this is not necessary for such a straightforward retrieval 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% for the single parameter 'last', which already explains it is the number of most-recent observations with a default of 10. The description uses 'N' to correspond to this parameter but does not add significant new meaning beyond the schema's own documentation.

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

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

The description clearly states the tool returns the latest N observations of the EUR/GBP spot rate, specifying the currency pair, the unit (€ per £1), and the series code (XUDLERS). This distinguishes it from sibling tools like usd_gbp and generic get_series.

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 when to use the tool: to obtain recent EUR/GBP spot rate data. The context is clear from the currency pair and series identifier, though it does not explicitly mention alternatives or exclusions. Since the name and description make the use case obvious, this is a clear context without explicit 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds context about clearing sensitive data and that it removes previously stored memories, aligning with the destructive nature without contradicting annotations.

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

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

Two sentences with zero wasted words. The description front-loads the action and object, then provides usage context and sibling references, making it highly skimmable.

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

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

For a simple one-parameter deletion tool with rich annotations and full schema coverage, the description covers purpose, usage timing, and even pairs related tools. No missing critical information for an agent to confidently invoke it.

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

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

Schema description coverage is 100% and clearly defines 'key' as 'Memory key to delete'. The description adds minimal extra meaning, only reinforcing that the key identifies previously stored memory, which is already implied by the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool deletes a previously stored memory by key, using a specific verb ('Delete') and resource ('memory'). It distinguishes from siblings by framing it as the counterpart to remember and recall, which are listed as sibling tools.

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

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

The description explicitly provides when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names related tools (remember and recall) to pair with, giving clear situational 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 it read-only, idempotent, and non-destructive. The description adds behavioral detail: it fetches the page, extracts title/description/key links, and emits a single text blob. This goes beyond annotations by explaining the process and output format, which helps the agent set expectations.

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

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

The description is two sentences plus a targeted list of use cases. It is front-loaded with the main purpose, and every sentence adds value. 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?

The tool is simple, with 2 well-documented params and strong annotations. The description explains the process, output format, and use cases, making it nearly complete. It could mention error behaviors (e.g., unreadable URLs) but that is not essential for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the parameters are already well-documented. The description adds context for 'url' (any URL, site-root) and mentions the output, but does not add meaningful info about 'max_links' beyond what the schema provides. 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 gives a specific verb ('Generate'), the resource (a production-ready llms.txt file for any URL), and the output format (standard llms.txt markdown). It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on generating the file itself rather than just auditing presence.

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

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

The 'Useful for' list provides clear contexts: getting a client's site indexed, drafting llms.txt for a project, or auditing a competitor. This gives strong usage guidance, though it does not explicitly name alternative tools or exclusion criteria, preventing a score of 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 return format details ('Returns parsed JSON: one entry per series with observations [{date, value}]') and context about the date range, going beyond the annotations.

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

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

The description is three concise sentences: purpose, prerequisites/alternatives, and return format. Every sentence adds value with no redundancy, and it is front-loaded with the primary function.

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

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

For a tool with no output schema, the description covers the return structure and prerequisites adequately. It lacks error handling details, but given the simple complexity, it is sufficiently complete.

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

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

Schema coverage is 100% with clear parameter descriptions, so the baseline is 3. The description adds concrete code-to-meaning mappings (e.g., IUDBEDR = Bank Rate) that enrich the semantic understanding beyond the schema.

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

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

The description clearly states it fetches BoE IADB series by code over a date range, with a specific verb and resource. It also differentiates from siblings by explicitly pointing to list_known_series and convenience tools (bank_rate, sonia, usd_gbp, eur_gbp).

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

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

It provides explicit usage guidance: requires BoE series codes and says to use alternative tools if the code is unknown. This clearly distinguishes when to use this tool vs. alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds that the tool returns friendly names paired with IADB codes, providing useful output context beyond the annotations.

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

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

The description is a single, concise sentence with no wasted words. It fronts the key verb and includes concrete examples for clarity.

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

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

For a tool with no parameters and no output schema, the description fully covers what it does and what it returns. It provides enough information for an agent to select and invoke it correctly without needing additional context.

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

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

The tool has zero parameters, so schema coverage is trivially 100%. The description adds no parameter-specific details, but none are needed. Baseline for no parameters is 4.

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

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

The description clearly states the tool lists friendly BoE series codes (with examples) and their IADB codes. The verb 'list' and specific resources make it distinct from sibling tools like bank_rate or sonia, which likely return series data.

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

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

The description implies this tool is for discovering available series and their codes, contrasting with siblings that fetch specific series. However, it does not explicitly state when to prefer this over alternatives, but the context is clear enough for a simple listing tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds behavioral context by specifying the exact fields returned (id, type, params, created_at, last_fired_at, fire_count) and clarifying it applies to the caller's subscriptions. It does not cover edge cases like pagination, but the annotations lower the burden.

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

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

The description is two sentences long, front-loaded with the main action, and includes only essential information: scope, return fields, and usage. Every sentence earns its place without unnecessary detail.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It explains what is listed, what fields are returned, and when to use it, which is sufficient for an agent to select and invoke the tool correctly.

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

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

The only parameter, include_inactive, is fully described in the schema with 'Include cancelled subscriptions in the response (default false).' The description adds no additional parameter semantics, so with 100% schema coverage, a baseline score of 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions', specifying the verb, resource, and scope. It also lists the returned fields, making it unambiguous. This distinguishes it from sibling tools like subscribe and unsubscribe by focusing on listing existing subscriptions.

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

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

The description provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use the tool and references the subscription lifecycle, implicitly guiding away from subscribe/unsubscribe for review purposes.

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

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

Annotations are all false and offer no behavioral context. The description compensates by disclosing rate limits ('Rate-limited to 5 per identifier per day'), quota impact ('doesn't count against your tool-call quota'), and organizational impact ('The team reads digests daily and signal directly affects roadmap'). These traits go beyond the schema and are vital for a feedback tool.

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

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

The description is four sentences, each earning its place: purpose, use cases, content guidance, and rate limit/quota. It is front-loaded with the core purpose and uses efficient, direct language. No filler or redundancy.

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

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

The tool has no output schema and a simple one-way submission, but the description covers the what, when, and how-to. It mentions the rate limit and ecosystem impact, which are key for a feedback channel. It could explicitly state what happens after submission (e.g., confirmation or no response), but given the simplicity, it is nearly complete.

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

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

Schema description coverage is 100%, so the schema already fully documents each parameter. The description does not add new parameter-level semantics, but it does reinforce message content guidelines ('Be specific') and context alignment with Pipeworx tools/packs. This matches the baseline for high schema coverage.

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

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

The description opens with a clear verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This precisely defines the tool's function and distinguishes it from sibling query/memory tools like ask_pipeworx or remember. The examples of bug, feature/data_gap, and praise further clarify scope.

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 cases: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides exclusion guidance: 'don't paste the end-user's prompt,' which helps avoid misuse. This is exemplary usage guidance.

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

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

The description goes beyond the readOnly/openWorld/idempotent annotations by disclosing the data source ('derived from CF analytics-engine'), privacy guarantees ('no PII'), the exact data shape ('just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). This is rich behavioral context that helps an agent anticipate performance and trustworthiness.

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

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

The description is concise (three sentences), front-loaded with the core purpose, and uses a numbered list for use cases. Every sentence adds value—purpose, use cases, and data provenance—without redundancy or fluff.

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

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

The description fully covers what the tool returns (top tools, top packs, total call volume), the data shape, caching, and privacy, even without an output schema. It is complete for a read-only analytics tool with one optional parameter.

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

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

Schema coverage is 100% and the parameter description already explains the window enum and its trade-offs ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The tool description only mentions the window in passing, adding no extra meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window.' It uses a specific verb ('Returns') and resource ('Pipeworx trending'), and distinguishes itself from siblings by focusing on what other AI agents are calling, a unique angle not present in sibling names.

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

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

The description provides explicit use cases ('Useful for: (1) discovering what data sources are hot... (2) confirming a popular tool is the canonical choice... (3) seeing whether your use case aligns...'). While it does not explicitly name alternatives or state when-not-to-use, the context is clear and actionable, justifying a near-top score.

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 open-world behavior, but the description adds substantial detail: Jaccard ≥0.30 similarity threshold, placeholder slug filtering, 3pp partition deviation threshold, live CLOB depth fill-check, and the distinction between theoretical and realizable edge. It also states 'do not trade it' under thin-book conditions — exactly the kind of context annotations can't convey.

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

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

The description is long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and a clear first-sentence summary. Every sentence contributes functional or safety-critical detail; the length is justified by tool complexity, though it still demands considerable reading time.

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 does an excellent job of explaining return fields like opportunities[] (gap_pp, suggested_trade, reasoning) and partition_check fields. It covers edge cases, fill-check pricing, and cross-tool references. Minor gaps exist around the exact output shape of trending_scan mode and how gap_pp is calculated, but overall it is largely complete for a complex tool.

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

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

While the schema already covers both optional parameters, the description adds meaningful value beyond it: concrete slug examples ('fed-decision-may-2026'), clarification that full Polymarket URLs are accepted, and a deeper explanation of what each mode does internally (walks child markets, checks date-axis, computes partition_check). This exceeds the provided schema 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 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks' — a specific verb, resource, and method. It clearly distinguishes the tool from siblings like polymarket_edges and polymarket_fill_risk by naming alternative uses and stating explicit 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 gives explicit usage guidance: no args for trending_scan, 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It even points to an alternative tool for custom sizing ('For custom sizing use polymarket_fill_risk') and tells users not to trade when realizable_edge_pp ≤ 0, covering both when to use and when not to.

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 substantial behavioral detail beyond the annotations: response structure (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread_pp, 24h-move warning), caching behavior ('Cached 1h at the KV level keyed on all knobs'), and notable quirks (Fed bets excluded from ranking, CONCENTRATED_LONGSHOT rare-by-design, gate relaxation in Run 8). This goes well beyond the read-only/idempotent annotations.

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

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

The description is front-loaded with purpose, but it is extremely long and dense, packing extensive detail into a single paragraph with minimal structural organization. While every sentence contributes useful information, the sheer length (400+ words) and lack of visual breaks reduce readability. It is not 'appropriately sized' for a typical tool description, earning a mid-range score.

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

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

Given there is no output schema, the description thoroughly explains the response top-level structure (by_segment, fed_candidates/fed_note, _diagnostics), per-opportunity fields, and diagnostics. It also covers caching and filtering behaviors. This provides a complete picture of what the caller can expect, making the tool well-specified despite the lack 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?

Schema coverage is 100%—all 9 parameters have detailed descriptions in the JSON schema. The description adds some semantic grouping ('TRADEABLE-EDGE KNOBS', 'min_partition_leg_kelly filters partitions') but does not provide substantive new meaning beyond what the schema already states. It meets the baseline for high schema coverage but does not significantly enhance parameter understanding.

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

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

The description clearly states the tool's function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb ('scan', 'return') and resource (Polymarket markets), and distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx data disagreement and opportunity discovery rather than arbitrage or 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 explicitly identifies the primary use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also provides guidance on adjusting knobs like min_liquidity, max_spread_pp, and min_partition_leg_kelly to filter opportunities, giving practical usage context. However, it does not explicitly contrast with sibling tools or state when not to use this tool.

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

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

The description discloses significant behavioral details beyond the annotations: the 60-day snapshot TTL, cache-miss snapshot gaps, and that decay is computed from daily closes rather than intraday data. This gives the agent crucial context for interpreting results, and there is no contradiction with the read-only/idempotent hints.

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

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

The description is well-organized with labeled sections (Args, RESPONSE, LIMITS) and every sentence adds meaningful information. Although moderately long, it is dense and front-loaded with purpose, making it easy to scan.

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 thoroughly explains the response structure (tracked, expired, snapshot_dates), limitations, and data source. It is self-sufficient for an agent to understand what the tool returns and how to interpret it.

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

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

Schema coverage is 100% and the schema describes both parameters well (defaults, clamps, allowed values). The description repeats the same information without adding new meaning, 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 states the tool's purpose: tracking edge persistence and decay telemetry from daily polymarket_edges snapshots, answering a specific question. It distinguishes itself from the sibling polymarket_edges by focusing on time-series analysis and edge age, not just current edges.

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

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

The description provides clear context on when to use the tool by stating the question it answers ('how long has this edge existed and is it shrinking?'). It also mentions data source and limitations, but does not explicitly name alternative tools or when not to use it, which is a minor gap.

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

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

Annotations already declare read-only and idempotent, but the description adds valuable behavior: 'walks the ladder', lists exact return fields per mode, and warns about 'forced_directional_risk naming the legs most likely to strand you unhedged.' This enriches beyond the annotations without any contradiction.

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

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

The description is long but every sentence earns its place. It is front-loaded with the core purpose, then uses clear mode-based sections, and ends with explicit usage guidance. The structure makes complex two-mode behavior easy to parse.

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

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

With no output schema, the description fully enumerates the return values for both modes. It covers prerequisites (market/event), parameter interpretations, edge cases (thin legs, forced directional risk), and the rationale for use — complete for an agent to safely invoke the tool.

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

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

Schema coverage is 100%, yet the description adds crucial semantics beyond the schema: size_usd is 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional — shares per leg' in basket mode. It also explains side defaults in both modes, which are not fully captured 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 opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market and basket) and explicitly names sibling tools that it complements, making its purpose unmistakable.

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

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

Explicit usage directive: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable, partial fills create unhedged positions), giving both when and why.

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 correctly aligns. It adds substantial behavioral context beyond annotations: two modes, response structure, compatibility_warning semantics, temporal_alignment conditions, skipped_cross_type/subtype counters, and the honest caveat that most pre-mapped topics return warnings. 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 but information-dense; every clause adds behavioral detail. It is front-loaded with the core purpose, then modes, response, and safety fields in a logical order. It loses a point because the dense prose lacks list formatting or clear section breaks, making it harder to scan, but nothing is redundant.

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

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

With no output schema, the description fully explains return values: leg-by-leg prices, matched spread[].top_spreads_pp, compatibility_warning cases, temporal_alignment, and skipped counters. It also covers edge cases (non-equivalent bet shapes, unrelated events, temporal mismatch) and the practical limitation that pre-mapped topics often yield no tradeable spread. This is exemplary for a complex tool.

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

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

Schema coverage is 100% and each property has a meaningful description. The tool description enriches those with mode semantics: 'topic' auto-fetches matching events, while explicit ticker/slug override the topic side. It explains how parameters interact ('Overrides the topic-mapped...'), which adds value beyond the schema's per-field descriptions.

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

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

The description opens with a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes the tool from sibling tools like polymarket_arbitrage by focusing on two-venue comparison for identical outcomes, and it defines the key output metric (Kalshi − Polymarket in percentage points).

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: two modes (topic shortcuts vs explicit event identifiers), when each is appropriate, and behavior when shapes are non-equivalent. It does not explicitly name alternative sibling tools for exclusions, but it strongly implies when the tool is and is not useful, e.g., 'pre-mapped ≠ tradeable' and when compatibility_warning indicates no arb exists.

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 readOnly, idempotent, and non-destructive. The description adds useful behavioral context: scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the listing behavior when key is omitted. This goes beyond the annotations.

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

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

The description is two sentences, front-loaded with the primary action, and every clause adds useful information without redundancy. It is appropriately sized for a simple 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?

For a tool with one optional parameter and no output schema, the description covers core behavior, scoping, and relationships with companion tools. It provides enough information for an agent to use it effectively.

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

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

The input schema already documents the 'key' parameter well, including the omit-to-list-all behavior. The description adds concrete examples of key values and clarifies that keys are saved via remember, enriching the 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?

The description clearly states the tool retrieves a previously saved value or lists all keys, using specific verbs and resource references. It distinguishes itself from sibling tools by mentioning 'remember' and 'forget' and describing the omit-key behavior.

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 the tool ('Use to look up context the agent stored earlier') and provides a rationale ('without re-deriving it from scratch'). It also pairs with remember and forget, giving clear guidance on related tools.

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

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

It adds valuable behavioral details beyond the annotations: the return payload composition (source, citation_uri, raw event payload), the mark_read side effect ('flag returned events read so the next call only shows newer ones'), and the polling compatibility. The annotations already indicate readOnly and idempotent, but the description enriches this with concrete 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 compact and front-loaded, with the main purpose stated in the first sentence. Every subsequent sentence adds useful information (return fields, filters, mark_read effect, polling/alternative access). No redundant or fluffy language.

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

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

Despite having no output schema, the description clearly explains what the tool returns (source, citation_uri, raw payload) and covers all key behaviors (filtering, mark_read, polling). Combined with the comprehensive schema, the tool is fully documented for an agent to use correctly.

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

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

The schema already covers all five parameters with descriptions (100% coverage), but the description adds semantic meaning by giving a concrete type example ('sec_8k'), clarifying the since format as ISO timestamp, and explaining the behavioral effect of mark_read. It doesn't mention limit or unread_only, but the schema handles those adequately.

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: 'Pull fired events from your subscription feed.' It specifies both the action (pull) and the resource (alerts from subscription feed), and this distinguishes it from siblings like list_subscriptions (which lists subscriptions) and recent_changes (which tracks changes).

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 practical usage context: it notes that 'Polls work fine,' suggesting repeated calls are acceptable, and it points to an alternative endpoint for scripts/dashboards ('GET registry.pipeworx.io/alerts.json'). However, it doesn't explicitly name sibling tools to avoid or contrast with, so it's not a full when/when-not guide.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context beyond these: multi-source fan-out to SEC, GDELT/GNews, USPTO; rate-limit handling; PatentsView API sunset causing soft-fail; and the ability to accept ISO dates or relative shorthand. This is rich supplementary disclosure.

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 densely packed with no wasted sentences. It opens with conversational examples to illustrate intended queries, then quickly moves into mechanism and return format. Every clause adds functional information, balancing length with comprehensiveness.

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 stating the return structure: 'returns structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' It also explains source composition, fallback logic, and the meaning of the `since` parameter. For a tool with 3 parameters, this gives a complete operational picture.

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

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

Schema covers all 3 parameters with useful descriptions (100% coverage), so baseline is 3. The description adds extra value by giving explicit examples for `since` ('7d', '30d', '3m', '1y'), recommending '30d' or '1m' for typical monitoring, and reinforcing that `value` can be a ticker or zero-padded CIK. This goes 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 uses multiple specific verbs and phrases ('What's new with X', 'change feed', 'Fans out to SEC EDGAR, GDELT→GNews, USPTO') that clearly define the tool's function. It explicitly contrasts with sibling tool entity_profile ('Use entity_profile instead when you want the static profile'), distinguishing this tool as the windowed-change 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 an explicit alternative: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also explains fallback behavior for data sources (GDELT preferred, GNews when rate-limited), which guides agents on expected tool behavior.

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 reveals persistence behavior (authenticated persistent, anonymous 24 hours) and per-identifier scoping, which go beyond the provided annotations. Annotations already indicate idempotent and non-destructive; the description adds storage lifecycle context. Does not detail overwrite semantics or return values, but this is minor.

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: purpose, usage trigger with examples, and persistence/scoping/related tools. Every sentence carries useful information, front-loaded with the action.

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

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

For a simple two-parameter setter, the description covers what, when, where (scoping), and how long memory persists, along with companion tools. Absence of output schema makes return details unnecessary.

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 clear descriptions for both key and value. The description's examples (ticker, address, preference) loosely align with value semantics but add little beyond the schema's 'findings, addresses, preferences, notes'. Baseline 3 is appropriate.

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

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

The description opens with 'Save data the agent will need to reuse later', a specific verb+resource, and clarifies scope across conversations/sessions. It explicitly names sibling tools recall and forget, distinguishing from them.

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

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

The description provides an explicit 'Use when' trigger with concrete examples (ticker, address, preference, research subject) and states it's for avoiding re-lookup. It also names alternatives: recall for retrieval, forget for deletion.

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 clear. The description adds substantial behavioral context beyond these: it discloses that each call 'cascades through several lookup endpoints internally,' that it auto-disambiguates company names, and it details exactly what is returned for each type (ticker, CIK, company_name, citation URI, RxCUI, ingredient, brand). This is valuable context that annotations cannot convey.

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

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

The description is front-loaded with trigger phrases and a crisp purpose statement, then dives into supported types and return details. Although it is longer than a minimal definition, every clause adds necessary information: the user intents, the 'Use FIRST' guideline, the type-specific return formats, and the internal cascading note. There is no redundancy, and the structure flows logically from intent to behavior to output.

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

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

For a tool with two entity types and no output schema, the description is fully complete. It explains the return values for both 'company' and 'drug,' including the citation URIs, and clarifies the internal cascade that replaces manual lookups. The complexity of supporting two different entity types with different identifiers is adequately addressed, and the description leaves no critical operational gap.

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

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

Schema coverage is 100%, and the schema already describes both parameters well. However, the description enriches this with accepted input formats per entity type (ticker, CIK, or name for company; brand or generic name for drug), concrete examples ('ozempic', 'AAPL'), and mentions auto-disambiguation. It also explains what the output will contain, making the relationship between input and output clearer than the schema alone.

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

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

The description opens with concrete user intents ("What's the ticker for…" / "find the CIK for…") and states a specific verb+resource: 'resolve a user-spoken NAME to the canonical/official identifier.' It clearly distinguishes from sibling tools by noting that other tools require the ID as input. The supported types (company, drug) further specify its scope.

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

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

The description provides an explicit directive: 'Use FIRST whenever you have a name but need an ID.' This clearly indicates when to reach for this tool. It also implies the alternative—if you already have an ID, you can skip straight to other tools—but doesn't explicitly name a 'when-not' scenario or list alternative tools. The instruction is strong and unambiguous enough for an agent to apply correctly.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description doesn't need to relitigate safety. It adds valuable behavior: internally probes each entity with ai_visibility_check, ranks by score, and returns score/confidence/signal density. It doesn't cover edge cases like API failures or rate limits, but the core behavioral disclosure is strong.

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

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

Three sentences, each earning its place: action, mechanism, and use case. No filler or repetition, and the structure is front-loaded with the primary purpose.

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

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

With no output schema, the description correctly explains the return value (ranked list with score, confidence, signal density). It also covers the internal probe mechanism and the intended context. The only missing piece is explicit mention of constraints like entity count or model restrictions, but those are present in the input schema, so 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?

The input schema already describes all four parameters with 100% coverage, so the baseline is 3. The description adds marginal context ('your brand + N competitors' for entities) but does not provide substantial semantics beyond the schema's own descriptions. It doesn't compensate for any gaps because there are none.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side', naming specific actions like ranking and surfacing most/least recognized. It distinguishes itself from sibling tools by referencing ai_visibility_check and the competitive audit use case, which is not apparent from the generic compare_entities sibling.

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?

A concrete use case is provided ('competitive AI-marketing audits') plus an example question, making it clear when to use the tool. However, it does not explicitly state when not to use it or name alternative tools for single-entity queries, so it stops short of a perfect 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses composite behavior, partial failure handling (sources_failed), and a critical latency caveat (bundlephobia first measurement 5-30s). It also lists the exact return fields, which is valuable given no output schema. No contradiction with annotations.

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

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

Every sentence earns its place: purpose, use-case, return payload, ecosystem limitation, and failure behavior. Information is front-loaded and well-structured; despite length, it remains scannable and efficient.

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

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

The description is remarkably complete for a composite tool with no output schema: it names both upstream services and their contribution, enumerates the summary block fields, describes advisory detail and links, explains ecosystem scope, and warns about latency and graceful degradation. This gives the agent a full mental model.

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

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

Schema coverage is 100% with both 'package' and 'version' already described, so the baseline is 3. The description adds ecosystem context (npm-only) and hints at version history in deps.dev, but doesn't substantially expand parameter meaning beyond schema.

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

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

The description opens with a specific composite verb+resource: 'should I add this npm package to my project' check that fans out across deps.dev and bundlephobia. It clearly distinguishes from siblings by being a one-call aggregate and npm-specific, unlike other tools like compare_entities or validate_claim.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion for non-npm ecosystems, directing to deps.dev:version directly, and implies alternatives through that scoping.

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 implementation details (BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation flag) and output characteristics (character offsets, similarity scores). This goes beyond the readOnlyHint/idempotentHint annotations, providing actionable behavioral context without contradicting them.

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

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

The description is well-structured: core function first, then usage context, workflow, and technical constraints. It is a bit dense at 5 sentences but every sentence adds value. It is front-loaded with the essential purpose and effectively 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?

Without an output schema, the description compensates by specifying the return type (top-N passages with character offsets and similarity scores) and truncation behavior. It also covers use cases, related tools, and technical limits, making it self-contained for an agent to decide when and how to invoke the tool.

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

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

Schema coverage is 100% with descriptive parameter entries. The description reinforces the 'text' parameter with real-world examples (SEC 10-K body, article) but does not add fundamentally new parameter semantics beyond the schema. A baseline score of 3 is appropriate since the schema carries the semantic load.

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

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

The description clearly states the tool does 'Semantic search INSIDE a fetched record' and provides concrete examples (SEC 10-K, article). It distinguishes itself from siblings by focusing on searching within already-retrieved text and explicitly mentions pairing with ask_pipeworx_grounded.

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

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

The description explicitly says when to use it: 'Use when the record is too big to cram into the prompt' and explains it saves context. It also names a complementary tool (ask_pipeworx_grounded) and describes the intended workflow, giving clear guidance on when this tool is appropriate over alternatives.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds ordering ('most recent first') and the series identifier (IUDSOIA), but does not disclose return format or other behavioral details. Given annotations, this is adequate but not rich.

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

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

The description is a single, front-loaded sentence that efficiently communicates the purpose and ordering. There is no redundant or extraneous text.

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

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

For a simple single-parameter read-only tool with strong annotations, the description is adequately complete. It could mention the return structure (e.g., array of date/value pairs), but the simplicity of the tool and the specificity of the series make this a minor gap.

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

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

The schema provides 100% coverage of the single 'last' parameter with a clear description and default value. The tool description's 'Latest N' reinforces the parameter but adds no new semantic information beyond what the schema already states.

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

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

The description clearly states the tool returns the latest N observations of a specific financial series (SONIA/IUDSOIA), including ordering (most recent first). The specific resource and scope make it distinct from sibling tools like bank_rate or get_series.

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

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

No guidance is provided on when to use this tool vs alternatives such as bank_rate or get_series. There are no prerequisites, exclusions, or recommended contexts mentioned.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description discloses that subscriptions persist, require an authenticated account, return a subscription id, and have an always-on feed. It also reveals operational limits like SMS cap and phone verification, adding meaningful side-effect and rate-limit context not captured by annotations.

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

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

The description is a single dense paragraph that front-loads the core action and return, then covers prerequisites, types, and delivery in order. It is efficient, but the structure could be improved with bullet points or clearer separation between types and delivery channels. Every sentence earns its place; no wasted words.

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

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

The description covers the main use cases and constraints, but omits two supported types (patent_grant, clinical_trial) and the webhook delivery channel, which are present in the schema. Since there is no output schema, the return value is mentioned, but the incomplete enumeration of types/channels leaves gaps for an agent attempting to understand the full tool capability.

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

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

The schema provides 100% coverage with detailed examples for all five types and delivery options. The description adds interpretive value, e.g., 'items:["5.02"] = officer change', and clarifies the return value. While it doesn't substantially enhance the schema's parameter documentation, the semantic hints (officer change example, delivery constraints) go slightly beyond the schema.

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

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

The description starts with 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This is a specific verb (create), a clear resource (subscription to an event stream), and it implicitly distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on the creation action.

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 prerequisites (requires Pipeworx OAuth account, anonymous + BYO cannot persist), lists supported types with example params, and includes delivery constraints (phone verification, 10/day SMS cap). It doesn't explicitly name alternative tools for when not to use, but the context is clear and comprehensive for the tool's own usage.

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

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

Annotations already declare read-only/idempotent/non-destructive. The description adds behavioral context about the output structure (category-bucketed examples with tool+argument shape), the live catalog, and the effect of passing a topic. 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 dense but every sentence contributes: user questions, purpose, return type, parameter semantics, and usage guidance. It is front-loaded with the entry-point hook and ends with actionable advice. Slightly long but not wasteful.

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

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

For a single-optional-parameter tool with no output schema, the description covers purpose, usage, parameter behavior, and expected return shape. It also points to related meta-tools for further learning, making it self-sufficient.

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

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

Schema coverage is 100% for the optional 'topic' parameter. The description enhances this by explaining the behavior when omitted ('full spread') vs. included ('to focus'), with concrete examples like 'finance' and 'pharma'.

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 identifies this as 'the onboarding entry point' that returns 'category-bucketed example questions' with exact tool and argument shapes. It clearly distinguishes itself from sibling tools by saying 'Use this FIRST when you do not yet know what Pipeworx can do for you.'

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

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

Provides clear 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 how to vary the call (no arguments vs. topic). However, it does not explicitly state when to use alternatives like discover_tools.

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

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

The description reveals that rows are deactivated rather than deleted, and that ownership is enforced, which goes beyond the annotation flags. It adds meaningful behavioral context such as retention of historical events via 'recent_alerts'. 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?

Two sentences, both dense with information. The first states the core action; the second covers enforcement and data retention. 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?

The description covers the key behavioral aspects (ownership, soft-delete) and the schema covers the parameter. However, there is no output schema and no mention of return values or error on invalid/non-owned IDs, which leaves a small gap for agent expectations.

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

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

The single parameter 'id' is already fully described in the schema with 100% coverage ('Subscription id (uuid) returned by subscribe'). The description does not add further syntactic details, so 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 uses a specific verb 'Cancel' with a clear resource 'subscription' and identifies the input method ('by id'). It is distinctly paired with sibling 'subscribe' and complements 'list_subscriptions', making its purpose unambiguous.

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

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

The description provides clear context that this tool cancels subscriptions, and it notes ownership enforcement. It does not explicitly name alternatives or exclusion criteria, but the operation is self-evident and contrasts directly with sibling 'subscribe'.

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

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

Annotations already cover read-only and non-destructive behavior. The description adds useful behavioral details: observations are returned most recent first and refer to a specific series (XUDLUSS). 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 a single, concise sentence that front-loads the primary function and includes essential details (currency pair, unit, series, ordering) without any wasted words.

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

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

For a simple one-parameter tool with strong annotations and no output schema, the description is complete. It explains what is returned (observations), the ordering, and the series identity, leaving no critical gaps.

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

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

Schema coverage is 100%, so the parameter 'last' is already well-documented. The description uses 'N' implicitly but adds no additional semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves the latest N observations of the USD/GBP spot rate, defines the rate as US$ per £1, and identifies the specific series (XUDLUSS). This distinguishes it from sibling tools like eur_gbp.

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 context of use is clear: it provides USD/GBP spot rate observations. However, it does not explicitly mention alternatives or exclusions, such as 'use eur_gbp for EUR/GBP,' which would elevate it to 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 indicate read-only, open-world, idempotent, and non-destructive behavior, and the description does not contradict these. It adds valuable behavioral context beyond annotations: the structured SEC EDGAR + XBRL fast path for company-financial claims, the grounded pipeline for other claims, the verdict types, verbatim evidence with pipeworx:// citation, and the fact that it replaces multiple sequential calls. This is richly transparent.

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

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

The description is moderately long but highly structured and front-loaded with query pattern examples. Each sentence adds value: usage, routing, output, efficiency. It is slightly redundant in places (e.g., 'natural-language claim verification' appears early), but overall it is 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?

Given the tool's complexity (2 params, no output schema), the description fully covers what the agent needs: the claim input, the tolerance parameter, the verdict types, the actual value with citation, and reasoning. It also explains the routing logic and the benefit over sequential calls. This is complete for invocation and interpretation.

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

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

Schema coverage is 100% for both parameters, and the description adds extra meaning: it gives example values for 'claim' and explains how to use 'tolerance_pct' (e.g., set 1–2 for hallucination detection). The description also clarifies the default behavior of tolerance_pct. This goes beyond the schema's basic field descriptions.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It uses specific verbs ('validate', 'verify', 'fact check') and differentiates itself from sibling tools like ask_pipeworx and deep_research by focusing on verifying user claims and returning a verdict. The two-path routing (company-financial vs other claims) further clarifies scope.

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

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

Provides explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the two routing paths and notes the tool replaces 4–6 sequential calls, which helps the agent choose it over more generic research tools. This is strong usage guidance.

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