Legislation Uk

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

Description goes beyond annotations by detailing default model (free), cost implications for Anthropic, and output structure (per-model score, confidence, signals, raw_response + combined view). No contradictions with readOnlyHint, idempotentHint, or destructiveHint.

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

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

Description is 4 sentences, front-loaded with core purpose, then defaults, then output, then use cases. No redundant or filler content.

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

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

Given no output schema, the description adequately describes return format. Combined with annotations and schema, it provides sufficient information for an AI agent to use this read-only tool correctly, including default behavior, optional parameters, and use cases.

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

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

All 4 parameters have schema descriptions, so baseline is 3. Description adds meaningful context: explains 'workers-ai' default, free usage, that _apiKey is only needed for Anthropic, and that context helps disambiguate. This exceeds 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?

Description clearly states the tool probes LLMs for entity visibility and scores it from 0-100 per model. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on any entity, not just competitors, and outlines the specific output format.

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?

Description lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use the _apiKey parameter. However, it does not explicitly state when not to use this tool versus alternatives like 'scan_competitor_ai_presence'.

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?

Description adds behavioral context beyond annotations: routes to 4,482 tools, returns structured answer with citation URIs. Annotations already indicate safe, non-destructive, read-only, but description enriches with routing behavior and source coverage.

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

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

Description is somewhat verbose with multiple paragraphs. While it is front-loaded with key instruction, it could be more concise without losing content. Some redundancy in listing examples.

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

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

Given the complexity (6 params, no output schema, but rich annotations), the description is comprehensive: explains purpose, when to use vs alternatives, examples, and behavior. No gaps for typical usage.

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

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

Schema coverage is 100%, so baseline 3. The description only provides examples of questions, not additional parameter semantics beyond what the schema already covers. No need to compensate.

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 answers factual questions from authoritative structured data, with specific verb 'ask' and resource 'Pipeworx'. It distinguishes from siblings like ask_pipeworx_grounded and deep_research by specifying their use cases.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and provides detailed when-to-use (factual, real-world entities) and when-to-step-up (grounded for hallucination-resistant, deep_research for broad questions). Includes examples and 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 safety traits (readOnly, openWorld, idempotent), and the description adds detailed behavioral context: routing through 4,482 tools, extracting answer only from result, returning specific refusal reasons. 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 concise and front-loaded with essential information. Each of the four sentences adds value, though it could be slightly more streamlined.

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

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

Given the complexity (6 parameters, no output schema), the description covers purpose, when to use, behavior, return structure with refusal reasons, and cost. It compensates well for the lack of output schema and is comprehensive for high-stakes usage.

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 required parameter 'question' with aliases. The description mentions that arguments are filled automatically but does not add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes from the sibling 'ask_pipeworx' by specifying it extracts answers only from tool results and is for answers that will be quoted or cited.

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 tells when to use (high-stakes reads, factual integrity required) and when to prefer the alternative 'ask_pipeworx' for casual lookups, including a note on extra cost.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds extensive behavioral context beyond annotations: fan-out mechanics, response shapes, resolver contract, parent event extraction, news fallback handling, safety short-circuits for low-confidence matches, wide-spread warnings, and resolution-rule risk. No contradiction with annotations.

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

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

The description is very long and dense with information. While it is front-loaded with purpose and usage, it could be more concise; some sections are verbose and repetitive, such as the exhaustive fan-out examples. Every sentence earns its place but at the cost of brevity.

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 (3 params, no output schema), the description is exceptionally thorough. It covers resolver confidence, parent event extraction, news fallback, safety mechanisms, wide-spread handling, resolution-rule risk, and response shapes. Addresses edge cases like closed markets and low-confidence matches, making it complete for an AI agent.

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

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

Schema coverage is 100%, so the schema already describes parameters. The description adds value by explaining accepted formats for 'market', default behavior for 'depth' and 'include_raw', and the effect of 'include_raw' on response size. This enriches the parameter meaning beyond the schema.

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

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

The description starts with a clear verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input formats and gives concrete use cases like 'should I bet on X', which distinguishes it from sibling tools such as polymarket_edges.

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

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

The description explicitly lists when to use the tool with examples like 'should I bet on X', and provides classifiers and fan-out examples that guide the agent on context. However, it does not explicitly mention when not to use it or compare to alternatives, though the purpose is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false. The description adds significant context: it makes parallel calls, returns citation URIs, and replaces 8-15 sequential lookups, giving a clear picture of performance characteristics. 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 dense and front-loaded with common query patterns, but could be better structured (e.g., separate sections for company vs drug). However, every sentence contributes value, and there is minimal redundancy.

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

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

Given no output schema, the description mentions 'paired data + pipeworx:// citation URIs' but does not detail exact output structure. It covers major behavioral aspects but could elaborate on error handling or edge cases (e.g., unknown tickers). However, the annotations (openWorldHint) mitigate some completeness concerns.

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% (both parameters described). The description adds substantial meaning beyond schema: explains 'type' enum values in detail (company pulls LATEST 10-K revenue, net income, cash, debt; drug pulls FAERS counts, FDA approval counts, active trial counts) and clarifies 'values' format (tickers/CIKs for companies, drug names). The maxItems/minItems constraints are also explained implicitly.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call, distinguishing it from sequential single-entity lookups. It specifies the data pulled for each type (SEC financials for companies, FAERS/drug data for drugs) and explicitly distinguishes from alternatives.

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

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

The description provides explicit when-to-use guidance ('ALWAYS PREFER over sequential single-pack lookups') and example queries. It details behavior for different entity types, including handling of off-calendar fiscal years for companies, and explains that results are sorted by primary metric so 'largest' queries work directly.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant context: account requirement (free vs paid), parallel execution across 4,482 tools, output format (findings packet with evidence, confidence, source, gaps), and latency (15-60s). 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 well-organized: prerequisite first, then core functionality, then usage details and caveats. Every sentence is informative. It is front-loaded with critical info (account requirement) and structured for quick scanning.

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 (many sources, parallel execution, detailed output), the description covers all essential aspects: prerequisites, functionality, output format, alternatives, limitations, and expected latency. No output schema exists, so the description fully compensates.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds further meaning: explains that depth controls number of facets (quick=3, standard=5, thorough=8) and that question should be broad/multi-part. This enriches understanding beyond the schema.

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

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

The description clearly states the verb 'research', the resource 'structured data sources', and explicitly distinguishes from siblings like ask_pipeworx and ask_pipeworx_grounded. It specifies the scope (1129 structured data sources) and the parallel execution nature, making the purpose unmistakable.

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

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

The description provides explicit guidance on when to use this tool: for broad/multi-part questions over structured data. It contrasts with alternatives: single lookups use ask_pipeworx, breaking news uses ask_pipeworx. It also warns of limitations (returns empty gaps for non-catalog topics). This leaves no ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is established. The description adds valuable behavioral context: it states that results are 'ready to call directly, no second schema lookup needed' and that it searches among available tools. This goes beyond what annotations provide and helps the agent understand the tool's interaction pattern.

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

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

The description is informative but not overly verbose. It front-loads the core purpose and usage guidance, then provides specific details. While it could be slightly more concise, every sentence earns its place by adding relevant context or examples.

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

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

Given the tool's complexity and the richness of schema and annotations, the description is complete enough. It explains the output structure (names, descriptions, schemas with examples) and the proper usage context (call first). The lack of an output schema is mitigated by the description's explanation of what results contain.

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 all parameters are already documented in the schema. The description mentions aliases for the query parameter and notes the limit parameter, but does not add new meaning beyond what the schema provides. Baseline of 3 is appropriate as the schema carries the full burden.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses specific action verbs like browse, search, look up, and discover, and lists numerous data domains, making it easy to understand exactly what the tool does. It distinguishes itself from sibling tools by focusing on tool discovery rather than performing a specific research task.

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

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

The description explicitly advises to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context for when to use the tool. It does not explicitly state when not to use it or list alternatives, but the usage guidance is sufficiently clear for an AI 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?

The description discloses behavioral traits beyond annotations: it's a parallel call, fans out across multiple sources, returns specific fields, and notes the patent sunset soft-fail. It does not contradict annotations (readOnlyHint, etc.).

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

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

The description is dense but efficient, front-loading example queries and key behavior. Every sentence adds value, though it could be slightly restructured for even clearer scanning.

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 and no output schema, the description fully explains return values (CIK, filings, fundamentals, patents, news, LEI) and edge cases (patent sunset). It is complete 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?

Schema coverage is 100%, so baseline is 3. The description adds meaningful context: ticker or zero-padded CIK format, and the fallback to resolve_entity for names. This enhances the schema descriptions without being redundant.

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: 'full cross-source profile of a US public company in ONE parallel call.' It uses specific verbs and resources, and distinguishes from sibling tools like resolve_entity by noting that names require a different tool.

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

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

The description explicitly advises when to use this tool ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view') and when not to ('Names not supported — use resolve_entity first'). This provides clear guidance on 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 indicate destructive and idempotent behavior. The description adds context about when deletion is appropriate (stale context, sensitive data), which provides behavioral guidance beyond the annotations without contradicting them.

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

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

The description is extremely concise: two sentences with no wasted words. The first sentence clearly states the action, and the second provides usage guidance and sibling tool references. It is well front-loaded.

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

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

For a simple tool with one parameter, no output schema, and clear annotations, the description adequately covers the tool's purpose and usage context. It could mention what happens if the key does not exist, but this is not essential given the simplicity.

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

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

The schema covers 100% of the parameter with a description for 'key'. The tool description does not add further parameter details beyond the schema, so it meets the baseline but does not exceed it.

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

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

The description clearly states the action (delete), the resource (memory), and the method (by key). It also distinguishes from sibling tools 'remember' and 'recall' by mentioning pairing, which clarifies the tool's role in the memory lifecycle.

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 scenarios: stale context, task completion, and clearing sensitive data. While it lacks explicit when-not-to-use guidance, the positive cases are well-stated and the pairing hint adds context.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds behavioral context by explaining it fetches the page, extracts content, and emits markdown. This goes beyond annotations, providing process details and clarifying output format.

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

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

The description is very concise: two main sentences plus a use-case list. Every sentence adds value, and the main action is front-loaded. No wasted words.

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

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

Given no output schema, the description explains the return value ('single text blob') and where it should be placed. The process is fully described for a two-parameter tool. All necessary context is present.

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

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

Schema coverage is 100% with clear descriptions. The description does not add new meaning beyond schema for parameters, only restating defaults. 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 generates a production-ready llms.txt file for any URL, with a specific verb and resource. It distinguishes itself from sibling tools by focusing on a unique output format and purpose for AI crawler indexing.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, or auditing a competitor. It lacks mention of when not to use or alternatives, but the context is clear 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 mark it as read-only and non-destructive. The description adds behavioral detail: returns specific fields (title, type, year, number, status, extent, enactment date, long-title summary, full-text URL), content is XML, fields are best-effort parsed, and a raw excerpt is included. This goes beyond what annotations provide.

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

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

Two sentences: first sentence states purpose with an example, second lists return fields and notes about content. No unnecessary words, front-loaded with key 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 retrieval tool with clear parameters and annotations, the description is sufficiently complete. It covers what is returned, the format (XML), and potential limitations (best-effort parsing). Lacks mention of error handling or rate limits, but these are not critical for completeness.

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 has 100% coverage of parameter descriptions. The description adds an example linking the three parameters (ukpga/2010/15) but does not provide additional meaning beyond the schema. 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 it retrieves metadata for a specific UK legislation by type, year, and number, with a concrete example (ukpga/2010/15 = Equality Act 2010). It differentiates from the sibling 'search_legislation' which would be for searching rather than retrieving a specific item.

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

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

The description implies usage for fetching a single piece of legislation when the type, year, and number are known. It does not explicitly state when not to use it or mention alternatives, but the context with sibling 'search_legislation' provides sufficient differentiation.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds minimal behavioral context beyond the annotations (e.g., returning specific fields, defaulting to active subscriptions). It does not contradict annotations.

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

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

The description consists of two concise sentences. The first sentence front-loads the purpose and output, and the second provides usage guidance. Every word earns its place with no unnecessary 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?

The tool is simple with one optional parameter and no output schema. The description adequately lists return fields and explains the parameter's effect. It could have added more about pagination or rate limits, but given the simplicity, 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% (the only parameter has a description in the schema). The description does not add any additional meaning beyond what the schema already provides for the parameter.

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

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

The description clearly states the tool's action: 'List the caller's active subscriptions.' It also specifies the exact fields returned, distinguishing it from sibling tools like subscribe and unsubscribe which perform different operations.

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

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

The description provides explicit guidance: '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 it (before subscribing or to get an id for unsubscribing), effectively differentiating it from sibling operations.

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

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

Discloses rate limit (5 per identifier per day), non-quota count, and how feedback is used (digests, affects roadmap). Annotations are all false; description adds context 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?

Five sentences covering all essential aspects: purpose, usage, behavioral details, and restrictions. No fluff; front-loaded with main 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?

Completely addresses a simple feedback tool: usage scenarios, parameter guidance, behavioral constraints, and team handling. No need for 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 description coverage is 100%, so the schema already documents parameters well. The description reinforces enum meanings but does not add significant new semantics beyond what the schema provides.

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

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

The description clearly states the tool's purpose: sending feedback about bugs, missing features, data gaps, or praise to the Pipeworx team. It is distinct from sibling tools which are query or research oriented.

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 scenarios (bug, feature, data_gap, praise) and what not to do (don't paste end-user prompt). Also mentions rate limit, free usage, and non-quota impact.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds context about the data source (CF analytics-engine), caching (5min-1h), lack of PII, and the self-aggregating nature. 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 slightly verbose but well-structured with a clear summary and bullet-point use cases. Every sentence contributes meaningful information. Minor trim could improve conciseness.

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

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

Given only one parameter (optional), no output schema, and annotations covering safety, the description is fully complete. It explains what is returned, time windows, caching, and use cases. No gaps exist for an agent to invoke this tool correctly.

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

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

With 100% schema description coverage, the schema already documents the window parameter. The description adds value by explaining the semantic difference between windows ('shorter windows surface what's hot right now; longer windows show steady-state demand').

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

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

The description specifies a concrete verb ('returns'), the resource ('top tools, top packs, and total call volume'), and the context ('recent window'). It clearly distinguishes the tool's purpose from siblings by enumerating three specific use cases, making it easy for an agent to know exactly what this 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 three explicit use cases for when an agent should invoke this tool, such as discovering hot data and confirming canonical tools. While it does not explicitly mention when not to use it or name alternative tools, the given guidance is clear and actionable.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond annotations by detailing monotonicity checks, partition-sum checks, semantic anchor (Jaccard similarity), partition filter, fill check against live CLOB depth, and conditions for null arb signals. 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 fairly long but well-structured: it front-loads the requirement, then explains modes, then specifics of checks and filters. Every sentence adds value, though some redundancy could be trimmed.

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

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

Despite the complexity (two modes, multiple checks) and no output schema, the description explains the response structure (opportunities[], partition_check, fill_check) and key behavioral aspects. It could be more explicit about return field details, but is largely complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining that `event` accepts slugs or full URLs, `topic` is a seed question, and how each parameter selects a mode of operation.

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

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

The description clearly states that the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It identifies two distinct modes (event and topic) and distinguishes itself from sibling tools like polymarket_edges, polymarket_edge_tracker, and polymarket_fill_risk.

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

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

The description explicitly requires one of `event` or `topic` and explains when to use each mode: event for a specific market, topic for cross-event scanning. It also mentions an alternative tool (polymarket_fill_risk) for custom sizing, but lacks explicit when-not-to-use conditions.

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

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

The description extensively details behavioral traits beyond annotations: the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), caching (1h at KV level), Kelly sizing, slippage, diagnostics like filter_skips, and specific edge calculations. No contradictions with annotations (readOnly, idempotent, openWorld).

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

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

The description is very long and information-dense, covering many details. While front-loaded with purpose, it could be more concise; some technical breakdowns (e.g., per-sport α values) add depth but reduce readability. A 3 acknowledges the trade-off between completeness and brevity.

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 (9 parameters, multiple model families, no output schema), the description is exceptionally complete. It explains top-level response structure (by_segment, fed_candidates, _diagnostics), edge fields, caching, and filtering logic. The tool is fully documented for an AI 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?

Schema coverage is 100%, so the description adds value by explaining parameter behavior beyond the schema, e.g., slippage_pp discusses Polymarket fees and bid/ask depth, min_partition_leg_kelly explains its application to partition legs, and tradeable-edge knobs are grouped conceptually. The extra context justifies a 4.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarkets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb 'scan', the resource 'Polymarket markets', and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by emphasizing its 'what should I bet on today' design.

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 includes a clear use case ('Built for what should I bet on today — agents discover opportunities without paging hundreds of markets') and explains knobs like min_liquidity and max_spread_pp. However, it does not explicitly state when not to use the tool or compare directly to sibling alternatives, though the context signals provide sibling names.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false, so the description does not need to repeat safety. It adds significant behavioral context: response structure (tracked, expired, snapshot_dates), trend computation, decay calculation, and limits like 60-day TTL. No contradiction.

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

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

The description is informative and well-structured, with separate sections for args, response, and limits. It is slightly verbose but every sentence adds value, and the main purpose is front-loaded.

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

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

Given no output schema, the description fully explains the return fields (tracked, expired, snapshot_dates) and their meanings. It also covers computation details (trend, decay_pp_per_day) and limitations (TTL, snapshot gaps). Complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for both parameters (days and window). The description adds minor enrichment ('lookback', 'snapshot family') but does not significantly deepen understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence rather than 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 explains the use case (comparing fresh vs. old edges) but does not explicitly state when not to use this tool or list alternatives. However, the context is clear enough for an AI to infer when to invoke it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds behavioral context (it is a risk check, not a trade execution), explains ladder walking, return fields, and warns about thin books. 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 fairly long but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET). It is front-loaded with the core purpose. Every sentence adds value, though it could be slightly more concise.

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

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

Given no output schema, the description thoroughly explains all return fields for both modes (e.g., top_of_book, vwap_fill_price, verdict; theoretical_sum, realizable_sum, capture_ratio, thin_legs, forced_directional_risk). It covers edge cases, risks, and usage context, making the tool self-contained.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra semantics: explains the two modes, defaults, interpretation of size_usd for single vs basket, and side auto-detection for baskets. It goes beyond the schema's parameter 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 it performs a 'Realizable-vs-theoretical edge check' against live order book depth. It explicitly distinguishes between single-market and basket modes, and its purpose is unique among siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description provides explicit usage guidance: '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 is not capturable on thin books, and partial baskets convert arb into directional risk).

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

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

Adds rich behavioral context beyond annotations: explains two modes, response structure (legs, top_spreads_pp), and safety fields (compatibility_warning, temporal_alignment, skipped counters). Annotations already declare read-only, idempotent, non-destructive, and description does not contradict 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?

Well-structured with front-loaded purpose and clear separation of modes and safety fields. Some redundancy and length, but justified by tool complexity. Concise enough for a 3-parameter 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?

Covers all necessary aspects: inputs, outputs, safety warnings, and limitations. Despite no output schema, the description thoroughly explains what the agent will receive (leg prices, spreads, compatibility flags, temporal alignment). Complete for informed tool selection.

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%; description adds meaning by explaining the interaction between topic and explicit parameters (overrides) and providing examples. Helps agent understand when to use each mode.

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 as a cross-venue spread calculator between Polymarket and Kalshi, with two distinct modes (topic shortcuts and explicit tickers). It differentiates from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

Provides clear context for usage (comparing same outcome across venues) and explicitly warns about the rarity of tradeable spreads. However, it does not explicitly name alternatives for when this tool should not be used (e.g., polymarket_arbitrage for single-venue arb).

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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds context about scoping and the relationship to remember/forget, which is useful beyond the annotations. No contradictions.

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

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

Description is moderately long but well-structured, front-loading the core action. It could be slightly tighter but efficiently covers necessary points.

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 fully explains behavior (return value or key list), scoping, and pairing with siblings. Nothing essential is missing.

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

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

With 100% schema coverage, baseline is 3. Description adds nuance by providing examples of what the key might represent (e.g., user's target ticker). This extra semantic context justifies a 4.

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

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

The description clearly states the tool retrieves a value previously saved via remember, or lists all keys if omitted. It distinguishes from siblings (remember, forget) by specifying its read-only retrieval role.

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: to look up context stored earlier. Mentioned pairing with remember and forget, and notes scoping per identifier. Provides clear guidance on 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?

Describes side effects of mark_read (flagging events as read), which goes beyond annotations. However, annotations declare readOnlyHint: true, but mark_read modifies state, creating a minor contradiction. The description is transparent about the behavior.

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

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

Concise yet comprehensive: purpose stated upfront, followed by return data, parameter usage, and alternative endpoint. Every sentence adds value; no redundancy.

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

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

Complete for a polling tool without output schema: explains return data format, parameter effects, and integration alternatives. Covers all necessary context for correct invocation.

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

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

Adds significant meaning beyond schema: explains that events carry source, citation_uri, and raw payload; describes filtering by type and since; details mark_read behavior. Schema coverage is 100%, but description enhances understanding.

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

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

Clearly states the tool pulls fired events from subscription feed, specifying the resource (alerts) and action (pull/poll). Distinguishes from siblings like list_subscriptions by focusing on fetching events rather than managing 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?

Provides guidance on usage: mentions polling works fine, offers alternative GET endpoint for scripts/dashboards, and explains mark_read for read tracking. Could be improved by explicitly stating 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?

Discloses fan-out behavior, fallback from GDELT to GNews, soft-fail for patents, and return structure. Adds value beyond annotations which only indicate read-only, idempotent, non-destructive.

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

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

Well-structured with examples and fallback details, but slightly lengthy. Every sentence is useful, but could be slightly more concise.

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

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

Despite no output schema, the description adequately explains returned fields. Covers all critical aspects of the tool's behavior and sources.

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?

Adds significant meaning beyond schema: explains since accepts ISO or relative shorthand, recommends '30d' or '1m', and clarifies value can be ticker or CIK. Schema coverage is 100% but description enriches it.

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

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

The description clearly states the tool provides a change feed for a company covering SEC filings, news, and patents, and distinguishes itself from sibling entity_profile by specifying when to use that instead.

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

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

Explicitly tells when to use (for 'what's new' queries) and provides an alternative (entity_profile for static profile), making usage context clear.

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

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

Adds important context beyond annotations: scoping by identifier, persistence differences for authenticated vs anonymous sessions (24h retention), and pairing with recall/forget. No contradiction with annotations.

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

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

Three sentences, front-loaded with core purpose, no unnecessary words. Structure is optimal for quick scanning.

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 simple parameters and no output schema, the description covers use cases, session lifetime, and tool pairing completely. No gaps.

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

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

Schema coverage is 100%, so baseline 3. Description adds value with example key patterns (e.g., 'subject_property', 'target_ticker') and clarifies value as any text.

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

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

The description clearly states the verb 'Save data' and the resource 'memory', with explicit usage context 'later reuse across sessions'. Distinguishes from siblings 'recall' and 'forget'.

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

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

Provides explicit guidance: 'Use when you discover something worth carrying forward' and mentions when not to use (pair with recall/forget). Names alternatives directly.

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

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

Annotations already indicate read-only, idempotent, open-world behavior. The description adds significant behavioral context: it reveals that each call cascades through several internal lookup endpoints, describes the exact return fields per entity type (including citation URIs), and notes auto-disambiguation for company inputs. This goes well beyond what annotations provide and fully discloses the tool's operation.

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 yet comprehensive, front-loading with user-facing examples that quickly convey the tool's purpose. Every sentence adds value, and the information is logically structured: usage guidance, supported types with details, and internal behavior. No unnecessary words or repetition.

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

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

Given the tool's two parameters and no output schema, the description is remarkably complete. It covers input formats, supported entity types, return fields, internal processing, and usage priority. It even provides citation URI patterns, which would otherwise be unknown. No gaps remain for an agent to misuse 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%, so baseline is 3. The description adds semantic value by providing concrete examples for each parameter value (e.g., ticker 'AAPL', CIK '0000320193', drug names 'ozempic', 'metformin') and explaining auto-disambiguation. This helps the agent understand valid input formats and behaviors beyond the schema's enum and description.

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

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

The description clearly states the tool's purpose: resolving a user-spoken name to a canonical/official identifier needed by other tools. It uses specific verbs ('resolve', 'look up', 'find') and defines the resource (names to IDs) with concrete examples. While it does not explicitly differentiate from sibling tools, it implicitly positions itself as the first lookup step, which is sufficient given its unique focus on identifier resolution.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear guidance on when to use this tool. It also mentions that using resolve_entity replaces 2-3 manual lookups, emphasizing efficiency. However, it does not specify when not to use it (e.g., if an ID is already known) or mention alternative tools by name, so it has clear context but lacks exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral details: probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and specifies return fields (score, confidence, signal density). 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 four front-loaded sentences with no redundancy. Each sentence serves a purpose: state action, explain mechanism, give use case, describe output. It is efficient and well-structured.

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

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

Despite lacking an output schema, the description covers return values (ranked list with score, confidence, signal density per entity). It explains the composite nature of the tool (calling ai_visibility_check) and notes the first entity as subject. Combined with annotations, 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 descriptions for all parameters. The description adds marginal value by clarifying that the first entity is treated as the 'subject' for narrative purposes, which is not in the schema. It also gives example context usage, but overall the schema does most of the work.

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

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

The description clearly states a specific verb+resource: "Compare AI visibility across multiple entities side-by-side." It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison) by detailing that it probes each entity with ai_visibility_check and ranks results.

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 a clear usage context: competitive AI-marketing audits, with a concrete example. It implies when to use it for multi-entity comparison versus single-entity checks, but does not explicitly list alternatives or when not to use it.

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

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

Beyond the readOnly and idempotent annotations, the description explains that bundlephobia's first measurement can take 5-30s and that partial failures degrade gracefully with sources_failed listed. This adds critical behavioral context for the AI agent.

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 well-structured, starting with a summary, then usage, return value, limitations, and behavior. Every sentence provides essential information without excess verbosity.

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 (composite check, multiple sources, partial failures, ecosystem limitation), the description covers all key aspects. It lists return fields explicitly even without an output schema, making it complete for an AI agent.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by noting that scoped packages are accepted and that version defaults to latest when omitted, going beyond the schema's basic description.

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

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

The description clearly states it's a composite check for 'should I add this npm package', combining deps.dev and bundlephobia data. It specifies the return fields and distinguishes itself from sibling tools, none of which perform this npm package analysis.

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

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

Explicitly says to use when agent asks about safety, popularity, size, or cost of an npm package. Also notes the ecosystem limitation (NPM only) and suggests an alternative for other ecosystems via deps.dev:version directly.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds value by specifying the data source (legislation.gov.uk Atom feed), document types, and that full-text URLs are returned, going beyond the annotation set.

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 concise and front-loaded with the main action, but the listing of document types is redundant with the schema and could be shortened, slightly reducing efficiency.

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

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

Given 4 parameters fully described in schema, no output schema, and a search tool, the description covers source, type, and URL return. It lacks explicit result format details but is adequate for agent selection.

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

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

Schema coverage is 100%, so the baseline is 3. The description repeats the document type list already in the schema, adding no new meaning or examples for parameter usage.

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

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

The description clearly states the action (search) and resource (UK legislation), specifies matching by title words and optional year, and distinguishes from siblings like 'get_legislation' which retrieves specific documents.

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

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

The description implies usage for searching UK legislation, but does not explicitly contrast with sibling tools like 'search_within' or provide when-not-to-use guidance. The mention of 'UK legislation only' is implicit context.

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

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

Annotations already declare safe read-only behavior. Description adds technical details (BGE-base-en, cosine, 500-char windows, 200K char cap with truncation flag) and explains character offsets for verification.

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?

Concise (5 sentences) with front-loaded purpose. Each sentence adds value, no redundancy.

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

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

Despite no output schema, description explains return format (passages with offsets and scores), embedding technique, and limits. Pairs well with sibling tools, offering complete guidance.

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

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

Schema coverage is 100% with descriptions for all parameters. Description adds examples for query and typical usage but does not provide new information beyond schema. Baseline score 3.

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

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

Clearly states semantic search inside a fetched record, with specific verb and resource. Distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and saving context.

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

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

Explicitly advises use when record is too large for prompt and mentions pairing with ask_pipeworx_grounded. Does not provide exhaustive exclusions but gives clear context.

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

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

Discloses behaviors beyond annotations: returns new subscription id, requires OAuth, details on delivery channel limits, webhook signing. Annotations indicate non-read-only, idempotent, open-world; description aligns and adds context.

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

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

Well-structured with clear sections for types and delivery channels, front-loaded with purpose. Very detailed but concise; slightly long but each sentence adds value.

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

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

Covers all necessary context: required OAuth, type enum with param examples, delivery options with constraints, return value. No output schema but mentions id return, which is sufficient for a create operation.

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

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

Schema coverage is 100%, yet description adds significant value by explaining type-specific params with concrete examples (e.g., sec_8k items, polymarket_edge topic), and delivery object constraints. Significantly enriches 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 creates a proactive monitoring subscription to a live-data event stream, using specific verbs and resources. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

Provides explicit guidance: requires Pipeworx OAuth account (not anonymous/BYO), lists supported types with examples, and describes delivery channels with constraints (SMS cap, webhook auto-disable). Implicitly tells when not to use (if no OAuth).

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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds beyond these by explaining the tool returns example questions and serves as an onboarding guide. No behavioral traits like auth or rate limits are needed for this simple info tool, so the additional context is sufficient.

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

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

The description is comprehensive yet well-structured. It front-loads the core purpose ('onboarding entry point') and then lists categories and usage instructions. While every sentence adds value, it is slightly verbose; a more concise version could be achieved without losing essential information.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. It explains what the tool does, when to use it, what it returns (category-bucketed example questions with tool shapes), and how to control scope. No missing information is apparent.

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 defines the 'topic' parameter with a description of allowed values. The description enriches this by explaining usage context: omit for cross-category spread or pass a topic like 'finance' to focus. Since schema coverage is 100%, the baseline is 3; the extra guidance raises the score.

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 as an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It distinguishes itself from siblings like 'discover_tools' and 'ask_pipeworx' by focusing on suggesting questions rather than listing tools or answering directly.

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

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

The description explicitly advises using this tool first when unfamiliar with Pipeworx, and specifies calling with no arguments for full spread or passing a topic to focus. While it does not explicitly list exclusions, the context makes it clear when to use it versus alternatives like 'ask_pipeworx' or '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?

Description reveals important behavioral traits beyond annotations: the row is deactivated (not deleted) and historical events remain available. This adds value beyond the annotations (destructiveHint=false) and clarifies the side effect.

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

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

Description is concise with three sentences, each adding distinct value: purpose, ownership constraint, and behavioral detail. Front-loaded with the core action. No unnecessary words.

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

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

Given the single parameter, no output schema, and presence of annotations, the description is fully complete. It covers purpose, constraints, and side effects adequately for an agent to decide and invoke correctly.

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

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

Schema coverage is 100% and already describes the 'id' parameter as 'Subscription id (uuid) returned by subscribe.' The description adds no new semantic meaning beyond what the schema provides.

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

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

Description clearly states 'Cancel a subscription by id', using a specific verb and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying the action and ownership enforcement.

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?

Description provides clear guidance that ownership is enforced ('you can only cancel your own subscriptions'), but does not explicitly state when not to use or mention alternatives. The context is sufficient for an agent to understand usage conditions.

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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint, so the tool is safe and non-destructive. The description adds behavioral context: it returns a verdict, structured form, actual value with citation, and percent delta. It explains the data source (SEC EDGAR + XBRL) and what it replaces. 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 front-loaded with example queries, then gives usage guidance, scope, and return details. It is well-structured and each sentence adds value. Slightly verbose but not excessive; could be tightened slightly without losing information.

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

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

Despite lacking an output schema, the description explains the return values (verdict types, structured form, citation, delta). It also covers the data source and the fact that the tool is limited to company-financial claims. Missing details on error handling or edge cases, but overall complete for the complexity level.

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

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

Schema coverage is 100% with a clear description for the single 'claim' parameter. The tool description also provides examples of what claims look like, adding extra context beyond the schema. This justifies a score above the baseline of 3.

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

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

The description clearly states the tool's purpose: verifying natural-language claims against authoritative sources. It uses specific examples ('Is it true that...') and explicitly mentions the domain (company-financial claims for US public companies). It distinguishes itself by claiming it replaces 4-6 sequential calls, differentiating it from sibling tools.

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

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

The description explicitly tells when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also defines the scope (v1 supports company-financial claims for public US companies). It does not explicitly state when not to use or provide direct alternatives, but the scope is clear enough.

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