Uk Contracts

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by explaining the default model, the need for an API key for Anthropic, and the return structure (per-model results + combined view). 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 two sentences long, each earning its place. The first sentence covers purpose and scoring. The second sentence covers model options, pricing, and return value. 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 the tool's complexity (4 parameters, no output schema), the description sufficiently covers all needed information: what it does, how to use each parameter, what it returns (per-model structure), and use cases. 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 is 3. The description adds meaning beyond the schema: explains the default model for 'models', that '_apiKey' is passed directly to Anthropic, and that 'context' helps disambiguate. This adds practical guidance for 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 uses specific verbs ('probe', 'score') and resources ('LLMs', 'visibility') and distinguishes this tool from siblings by focusing on AI visibility scoring for brands/products. It clearly states what it does and contrasts with other tools like 'ask_pipeworx'.

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

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

The description explicitly states use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and provides context on when to use certain models (default vs. requiring an API key). It doesn't explicitly mention when not to use, but the guidance is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, establishing safety. The description adds that the tool routes to one of 4,552 tools across 1160 sources and returns structured answers with citation URIs, providing useful behavioral context beyond annotations.

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

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

The description is fairly long but well-organized: it starts with a strong directive, then lists supported areas, provides examples, and gives upgrade guidance. While a bit verbose, every sentence serves a purpose, and the structure helps the agent quickly grasp when to use this 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?

Given the high complexity (many sources, no output schema), the description adequately covers the tool's capabilities, output format, and differentiation from siblings. It doesn't detail return values but compensates with rich usage guidance and examples.

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 6 parameters (all aliases for 'question'). The description adds value by listing example questions and clarifying the natural language input format, which helps the agent formulate queries, though the schema already documents the aliases.

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 routes questions to a vast set of sources for authoritative structured data, listing many example domains (SEC filings, FDA, etc.). It distinguishes from siblings like ask_pipeworx_grounded and deep_research, making the purpose unambiguous.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and provides specific advice on when to use alternatives (e.g., ask_pipeworx_grounded for hallucination-resistant single answer, deep_research for broad multi-part questions). It also gives example query phrasings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral details: costs one extra LLM call, defines refusal reasons, and explains that it pulls data from 4,552 tools across 1,160 sources. 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 comprehensive and front-loaded with the key concept. While somewhat lengthy, every sentence serves a purpose (explaining behavior, usage, and structure). Could be slightly tighter but is well-organized.

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

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

Given the high stakes, number of sibling tools, and absence of output schema, the description is remarkably complete. It covers usage guidelines, behavioral traits, return format (including refusal reasons), and source details. Handles complexity well.

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

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

Schema coverage is 100% with 6 parameters (question and 5 aliases). The description mentions 'Your question in natural language' but does not add significant meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads'. It specifies that it extracts answers using only tool results and provides structured output with evidence and refusal reasons. It distinguishes itself from the sibling 'ask_pipeworx' by highlighting the extra safety and cost.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples (financial, legal, medical). It also advises preferring 'ask_pipeworx for casual lookups', providing clear usage boundaries.

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?

Extensive behavioral details beyond annotations: resolver contract with match_confidence, market_match_score, alternatives, suggestions; parent_event extractor; news fallback mechanism; safety short-circuits with specific status strings; wide-spread handling; cancellation rule parsing. Annotations (readOnlyHint, idempotentHint, destructiveHint) are consistent with description.

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 logical sections (purpose, usage, classifiers, fan-out examples, response shapes, safety), but fairly long. All sentences are informative, but some reorganization could improve scanability. However, for a complex tool, this level of detail is justified.

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

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

Covers all critical aspects: resolution logic, fan-out examples, response shape details, safety conditions, cancellation rules, and edge cases. No output schema, but description sufficiently explains return values. Leaves no gaps for an agent to operate 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?

Description adds significant meaning to all parameters beyond schema: market parameter examples, depth enum values explained with 'quick = 2-3 evidence sources, thorough = full fan-out' and default, include_raw explained with size implications. Schema coverage is 100% but description still 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 researches a Polymarket bet by pulling Pipeworx data in one call. It specifies the verb 'research' and resource 'Polymarket bet data via Pipeworx', and distinguishes from siblings like polymarket_arbitrage and polymarket_edges by offering comprehensive research with evidence packet and 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?

Explicitly provides use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Includes classifiers and fan-out examples to guide when to use. Also gives safety warnings (low-confidence matches, closed markets, wide spreads) that help the agent decide when the tool is appropriate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral detail: it explains data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), off-calendar fiscal year handling, sorting by primary metric, and the efficiency gain ('Replaces 8–15 sequential lookups'). 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 longer than average, but it is well-structured: query examples first, then core behavior, then per-type details, then output notes. Every sentence adds value; there is no fluff. The length is justified by the complexity of the tool. A slight reduction could be made, but overall it's well-organized and front-loaded.

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

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

Given no output schema, the description mentions return format ('paired data + pipeworx:// citation URIs') but could elaborate on the structure of 'paired data' (e.g., metric names, ordering). However, it sufficiently covers inputs, behavior, and output nature. For a tool of this complexity, it is mostly 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% (both parameters described), but the description goes far beyond: it clarifies what data each 'type' option retrieves (financial metrics vs. adverse-event/trial counts), provides input format examples (tickers/CIKs for company, drug names for drug), and explains sorting behavior. This adds significant meaning that the schema alone does not convey.

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

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

The description opens with concrete query examples ('Compare X and Y', 'rank these companies'), then explicitly states the tool performs 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It clearly distinguishes from sibling tools (e.g., entity_profile) by emphasizing batch comparison over sequential lookups. The verb+resource is specific and unambiguous.

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

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

The description explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance. It also lists example queries that trigger this tool. While it doesn't explicitly state when NOT to use, the context (sibling tools like entity_profile for single entities) and the min/max constraints (2–5 entities) implicitly cover 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?

Adds rich behavioral context beyond annotations: account requirement, decomposition into facets, parallel execution (4,552 tools), return format (findings packet with citations, gaps array, never invented), and expected latency (15-60s). No contradiction with 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?

Description is lengthy but well-structured: account prerequisite first, then core functionality, example use cases, return format. Every sentence adds value, though some phrasing could be tightened (e.g., 'in ONE call' emphasized multiple times).

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

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

For a complex research tool with no output schema, the description is highly complete: covers prerequisites, behavior, output structure, limitations (current news), and expected performance. Leaves no major gaps for an AI agent to understand when and how to use it.

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

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

Schema covers both parameters (question, depth) with descriptions. The description adds concrete meaning: depth enum values correspond to 3, 5, or 8 facets; question can be broad/multi-part. Enriches beyond schema but schema already provides solid coverage.

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

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

The description clearly states the tool performs 'grounded multi-source research across Pipeworx's 1160 STRUCTURED data sources' in one call, with explicit distinction from sibling tools like ask_pipeworx (single lookup) and guidance for different query types.

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

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

Provides explicit when-to-use and when-not-to-use: best for broad/multi-part structured data questions, advises ask_pipeworx for single lookups or breaking/current-news topics, and notes account requirements (free tier vs paid plan for 'thorough' depth).

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, non-destructive behavior. The description adds value by detailing the output format ('returns top-N most relevant tools with names, descriptions, and full input schemas') and that results are directly callable, which goes beyond the annotations.

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

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

The description is efficient with about 4 sentences, front-loaded with the main action. The list of domains is somewhat lengthy but informative and serves as concrete guidance.

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

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

For a tool with no output schema, the description fully explains the return value and use case. It covers parameter variants, expected input style, and the actionable output, making it self-contained for an agent.

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

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

Schema description coverage is 100% so baseline is 3. The description adds value by giving concrete examples of acceptable queries and reinforcing alias acceptance, which helps an agent craft effective queries.

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 distinguishes itself from sibling tools by explicitly recommending it as a first step when exploring options, and lists numerous domains it covers.

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

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

The description gives explicit when-to-use guidance ('Use when you need to browse, search, look up, or discover what tools exist') and instructs to call it FIRST. It lacks explicit when-not-to-use information, but the context implies direct tool calls when the tool is known.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by detailing the parallel fan-out across multiple sources (SEC EDGAR, XBRL, etc.), the soft-fail for patents, and the specific return structure. However, it does not fully describe error handling beyond the patent sunset note.

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 detailed and front-loaded with example prompts, making it easy to understand. It is slightly verbose with source enumeration but remains well-structured. Every sentence adds value, though some details could be condensed.

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

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

Given the absence of an output schema, the description thoroughly explains return values (CIK, filings, fundamentals, patents, news, LEI) and constraints (no names, soft-fail for patents). It covers all necessary context for the tool's use in complex queries.

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

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

Schema coverage is 100%, with both parameters having descriptions. The description does not add new meaning beyond what the schema already provides for parameters, meeting the baseline. The description focuses on overall purpose rather than parameter specifics.

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

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

The description clearly defines the tool's purpose as providing a full cross-source profile of a US public company in one parallel call. It uses specific verbs like 'research' and 'brief me on' and distinguishes from siblings by explicitly stating it should be preferred over chaining single-pack lookups for holistic queries.

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 use this tool over chaining single-pack lookups for holistic views, and warns that names are not supported (use resolve_entity first). It also notes the soft-fail for patents, providing clear when-to-use and when-not-to-use guidance.

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

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

Description states 'delete,' which aligns with destructiveHint=true and idempotentHint=true from annotations. It adds slight context (memory stored by agent) but does not significantly expand beyond annotations. 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?

Two sentences: first defines action, second gives usage guidance. No wasted words, front-loaded with purpose.

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

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

For a simple delete tool with one parameter and annotations present, the description is adequate. It covers purpose and usage but could mention idempotency or behavior on nonexistent key, though annotations already cover safety.

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 one parameter 'key' described as 'Memory key to delete.' The description does not add extra meaning beyond the schema, so baseline score applies.

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

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

Clearly states 'Delete a previously stored memory by key,' which is a specific verb and resource. Siblings include 'remember' and 'recall,' so 'forget' is distinct as the inverse operation.

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

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

Explicitly states when to use: when context is stale, task done, or to clear sensitive data. Also mentions pairing with 'remember' and 'recall,' providing clear usage context.

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

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

The description outlines the tool's behavior: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This aligns with the annotations (readOnlyHint, idempotentHint, openWorldHint) and adds valuable context beyond the annotations, such as the extraction process and output format. 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 concise with two sentences. The first sentence states the primary purpose and process, and the second lists use cases. Every sentence adds value, and the most important information is front-loaded.

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

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

Given the tool's simplicity (two parameters, read-only, no output schema), the description is complete. It covers what the tool does, how it works, and why it's useful. The annotations already provide safety and idempotency context, and the description complements them well.

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

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

The input schema descriptions cover both parameters completely (100% coverage). The tool description does not add any additional meaning beyond the schema; it repeats 'any URL' but does not elaborate on the parameters. According to the guidelines, when schema coverage is high, baseline is 3, which is appropriate here.

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

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

The description clearly states the verb 'generate', the specific resource 'llms.txt file', and the context 'for any URL'. It also briefly explains the output format and the tool's purpose for AI crawlers. The tool's name and title are well explained, and there is no confusion with sibling tools, which are mostly unrelated.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting for own project, and auditing competitors. This provides clear context on when to use the tool. However, it does not mention when not to use it or suggest alternatives, which would be needed for a perfect score.

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

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

The description adds 'Keyless' (no authentication) and lists the return fields, providing behavioral context beyond the annotations which already indicate read-only, idempotent, and non-destructive traits.

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 concise sentences with no redundant information. The purpose, usage, and output are efficiently communicated.

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

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

For a simple tool with one parameter and no output schema, the description fully covers what the tool does, how to invoke it, what it returns, and essential behavioral info (keyless).

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 detailed description for 'id'. The tool description adds the id format and source (from search/recent results), reinforcing and extending 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 gets full OCDS detail for a single notice by release id, distinguishing it from siblings like search_notices that return lists.

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 links the id parameter to results from search_notices/recent_notices, indicating when to use this tool. However, it does not explicitly state when not to use it.

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

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

Annotations already provide rich safety information (readOnlyHint, idempotentHint, destructiveHint). The description adds behavioral context by detailing the returned fields, which complements the annotations without 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 two sentences long, front-loaded with the main purpose, and every sentence adds value. 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 low complexity (one optional parameter, no output schema), the description provides sufficient information about what the tool returns and when to use it. It is complete for an agent to select and invoke correctly.

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

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

The single optional parameter 'include_inactive' is well-described in the schema with 100% coverage. The description does not add further semantics, so baseline score of 3 is appropriate.

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

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

The description clearly states it lists the caller's active subscriptions and enumerates the returned fields. It distinguishes from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

The description explicitly advises when to use the tool: to review monitored subscriptions before adding more or to find an id to cancel. This provides clear context 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?

Discloses rate-limiting ('5 per identifier per day'), quota-free behavior ('doesn't count against your tool-call quota'), and how feedback is used ('team reads digests daily and signal directly affects roadmap'). Adds significant context beyond annotations.

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

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

Every sentence adds value—purpose, usage, content guidelines, behavioral notes. No redundancy; efficiently conveys all needed information in a compact form.

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?

Fully covers the tool's purpose, parameters, usage constraints, and behavioral impacts. No output schema needed, and the description is sufficient given the tool's simplicity.

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

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

Schema coverage is 100%, but the description adds nuance: 'Describe the issue in terms of Pipeworx tools/packs' and warns against pasting user prompts. This enriches the meaning of the 'message' parameter beyond the schema 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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies sub-purposes (bug, feature/data_gap, praise), distinguishing it from sibling tools like ask_pipeworx and discover_tools.

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

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

Explicitly tells when to use: 'when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also advises what not to do: 'don't paste the end-user's prompt.' Provides clear guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds valuable context: data source ('CF analytics-engine'), no PII, aggregation details, and caching behavior (5min-1h). 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?

Four sentences, no fluff. First sentence states purpose, second lists uses, third adds technical detail, fourth describes caching. Information is front-loaded and each sentence earns its place.

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

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

For a read-only tool with one parameter and no output schema, the description covers purpose, use cases, data source, privacy, and caching. It is fully sufficient for an agent to decide when to invoke this tool.

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

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

Schema coverage is 100% and includes a description for the single parameter 'window'. The tool description adds extra context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' which helps the agent choose appropriately. This goes beyond the schema 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 states exactly what the tool returns: 'top tools, top packs, and total call volume over a recent window.' It specifies the resource (Pipeworx trending data) and the verb (returns), and distinguishes it from siblings like 'discover_tools' which is about discovering tools generally, not trending.

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

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

The description lists three explicit use cases: discovering hot data sources, confirming canonical tools, and aligning use cases. It does not mention when not to use the tool, but the context is clear and it differentiates from other tools via purpose.

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

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

The description adds substantial behavioral context beyond annotations: it explains the fill check against live CLOB depth, warns against trading when realizable edge is ≤0, details the semantic anchor and partition filter, and describes signal generation (BUY/SELL EVERY LEG). No contradiction with annotations.

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

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

The description is well-structured, front-loading the purpose and then breaking down modes with clear headings. While lengthy, each sentence adds necessary detail for a complex tool. Minor redundancy (e.g., repeating 'BUY/SELL EVERY LEG') but overall efficient.

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

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

Despite no output schema, the description explains the response structure (opportunities[] with fields, partition_check object) and covers key logic like fill check and filters. It is sufficiently detailed for an agent to understand inputs, behavior, and expected output, though trending_scan response details could be slightly more explicit.

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, the description adds meaning by explaining the format for event (slug or URL) and topic (seed question), and detailing behavioral differences between modes. It also indicates which parameter is recommended for specific use cases, enhancing the schema's static types.

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: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific verbs and resources, differentiating it from sibling tools like polymarket_edges 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 provides explicit guidance for each mode: when to use no args (trending scan), event (specific market), and topic (cross-event scan). It also explains the advantage of cross-event mode over single-event and suggests using polymarket_fill_risk for custom sizing, effectively directing the agent to the appropriate tool.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: caching at KV level for 1 hour, response structure with diagnostics, and exclusion of Fed bets from ranking. 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-structured, breaking down segments and providing dense, valuable information. Every sentence adds detail, though it could be slightly more concise. It front-loads the purpose and segments.

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 9 parameters, no output schema, and complex functionality, the description is comprehensive. It explains response structure, diagnostics, caching, and filter effects, leaving no major gaps for an agent to understand the tool's behavior.

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 significant meaning beyond schema by explaining how edge is computed net of slippage, practical advice like bumping slippage for thin partitions, and filter behavior (min_kelly, min_edge_pp).

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It specifies the verb 'scan' and resource 'edges', and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on agreement with external data.

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

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

The description is built for the use case 'what should I bet on today', providing clear guidance. It explains tradeable-edge knobs and filters, but does not explicitly list when not to use or alternative tools, though context from siblings implies 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?

The description adds significant behavioral context beyond annotations: it explains the source (daily polymarket_edges snapshots), data limitations (60-day TTL, gaps when no scan), decay computation (from daily closes), and output fields. Annotations only provide read/idempotent hints.

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

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

The description is well-structured: opening question, parameter list, and detailed output explanation. It is somewhat verbose but front-loaded with key value. Every sentence contributes to understanding, though some repetition could be trimmed. Score 4.

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

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

Given no output schema, the description comprehensively explains the output structure (tracked[], expired[], snapshot_dates[]) and their fields, including details like trend computation and limitations. It fully compensates for missing schema and provides a complete picture of the tool's behavior.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining default values (days default 14, max 30) and clarifying the 'window' parameter as a snapshot family (24hr/1wk/1mo). It also integrates parameter usage into the output explanation, improving semantic understanding.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and if it's shrinking. It distinguishes itself from the sibling 'polymarket_edges' by focusing on time-series tracking, though it doesn't explicitly name 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 implies when to use this tool via the example comparing a fresh wide edge to a 3-week-old one, suggesting it is for evaluating edge age and decay. It provides context but does not explicitly state when not to use it or name alternatives, so it scores 4.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false; description adds behavioral traits: requires one of market or event, default values and clamping for size_usd, return fields including verdict and warnings about partial fills converting arb into directional position. No contradiction; adds significant context beyond annotations.

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

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

Description is a single paragraph that is somewhat long, but front-loads key info in CAPS (REQUIRES, SINGLE-MARKET, BASKET) and avoids redundancy. Could be slightly more concise, but structure is clear and content earns its place given complexity.

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

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

No output schema, so description fully explains return values and logic for both modes: list of fields (top_of_book, vwap_fill_price, verdict, etc.) and basket-specific details (capture_ratio, thin_legs, forced_directional_risk). With annotations providing safety profile, description is complete and actionable.

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%, but description adds meaning: explains side default and options in each mode, size_usd interpretation differs for single vs basket, clamp range (10-1,000,000) not in schema. Adds substantial value beyond schema.

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

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

The description clearly states it checks 'realizable-vs-theoretical edge against live CLOB order-book depth' and distinguishes two modes (single-market and basket) with specific return fields like verdict, capture_ratio, forced_directional_risk. No tautology; purpose is precise and distinct 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?

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround not capturable, partial basket fills cause unhedged directional position). Provides clear context for when to use vs. alternatives.

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

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

Annotations include readOnlyHint and idempotentHint. Description adds extensive behavioral context: explains compatibility_warning scenarios, temporal alignment constraints, skipped cross types due to metric mismatches, and the meaning of various response fields. 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?

Description is dense but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core purpose. Every sentence adds value; 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?

Despite no output schema, the description thoroughly explains all response fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, counters). Covers edge cases and limitations, making the tool fully understandable 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 baseline is 3. Description adds significant value: explains the topic enum values, describes override behavior for explicit parameters, and provides examples. Adds context beyond simple parameter definitions.

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

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

The description clearly states it is a cross-venue spread tool between Kalshi and Polymarket for the same resolving question. It specifies two distinct modes (topic shortcuts and explicit event identifiers), which differentiates it from sibling tools like polymarket_arbitrage that focus on single-venue spreads.

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?

Describes two modes with clear usage guidance: topic shortcuts for common macros and explicit tickers for custom pairings. Warns that most pre-mapped topics return compatibility_warning, advising when the tool is not appropriate. No explicit alternatives but implies other tools for single-venue analysis.

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

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

Annotations already convey read-only/idempotent/non-destructive. Description adds scoping to identifier and the dual behavior (key present vs. omitted). 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?

Three sentences are succinct and front-loaded with the core purpose. Each sentence adds value without excessive 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 simplicity (one optional param, no output schema, strong annotations), the description covers key aspects: retrieval, listing, scoping, and pairing with siblings. Minor omission about output format, but acceptable.

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

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

Schema coverage is 100% with a clear description of the optional key parameter. The tool description adds context about the type of values stored and the listing behavior, adding value beyond the schema.

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

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

The description clearly states 'Retrieve a value previously saved via remember, or list all saved keys' – a specific verb (retrieve/list) and resource (key-value store). It distinguishes from sibling tools remember and forget.

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

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

Provides concrete use cases (ticker, address, research notes) and mentions scoping. Though it does not explicitly list when NOT to use, it implies alternatives by referencing remember/forget.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds context about the mark_read parameter flagging events as read, affecting subsequent calls, and mentions polling suitability. 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 three focused sentences plus a note about alternative access. It front-loads the main action and returns format, with no extraneous details.

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

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

Given no output schema, the description adequately covers return fields. It also mentions the alternative URL. Could mention limit behavior or pagination, but limit is in schema. Overall fairly 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?

All 5 parameters have schema descriptions (100% coverage). The description adds examples for type (e.g., 'sec_8k') and since (ISO timestamp), and explains the effect of mark_read, enhancing 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 retrieves recent alerts from the evaluator's subscription feed, mentions specific fields returned, and distinguishes it from siblings like 'recent_notices' by specifying the source and 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?

The description mentions polling works fine and provides an alternative URL for scripts/dashboards, but does not explicitly state when to use this tool versus sibling tools like 'search_notices' or 'recent_changes'.

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

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

Annotations already declare readOnly/hint etc. Description adds specifics: fans out to SEC EDGAR, GDELT→GNews fallback, USPTO patents with soft-fail note. 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?

Slightly long but efficient. Front-loads query patterns. All sentences add value. Clear structure.

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

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

No output schema, but description mentions return structure (changes[], total_changes, citation URIs). Explains multiple sources and fallback. Adequate for 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%, so baseline 3. Description adds value beyond schema: explains `since` accepts ISO date or relative shorthand, `value` ticker/CIK, `type` only company. Provides examples.

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 (SEC filings, news, patents) in a recent window, with example queries. It distinguishes from sibling 'entity_profile' by noting static profile usage.

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 indicates when to use ('what's new' queries) and when not ('use entity_profile instead'). Provides fallback behavior (GDELT→GNews) and date syntax guidance.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint. The description adds ordering ('newest-first') and 'Keyless' (no key parameter), but does not disclose format or pagination beyond the shape reference.

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

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

Two sentences, no waste, front-loaded with the action and key details. Every sentence earns its place.

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

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

For a simple list tool with two optional parameters and annotations covering safety, the description is mostly complete. However, it relies on knowledge of 'search_notices'' shape for understanding return format, which may not be immediately clear.

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 only restates the stage filter option; it adds no new meaning beyond the schema.

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

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

The description clearly states the verb 'List' and the resource 'UK procurement notices from Contracts Finder', with ordering 'newest-first' and optional filtering by stage. It distinguishes itself from sibling 'search_notices' by mentioning 'Same compact shape as search_notices' and being 'Keyless'.

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 recent notices via 'most recent' and 'optionally filtered by stage', but does not explicitly state when to use this tool versus alternatives like search_notices or get_notice. The reference to 'Keyless' suggests no key parameter needed, but no direct comparison.

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?

No contradiction with annotations. Adds detail on scoping by identifier, persistence periods (24 hours for anonymous, persistent for authenticated), and cross-session storage beyond annotations.

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

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

Very concise and well-structured: purpose, usage guidance, storage details, sibling pairing. Every sentence earns its place with no redundancy.

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

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

Complete for a simple memory tool: explains what, when, how stored, scoping, and relation to siblings. No output schema needed as it's a side-effect 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%, but description adds value by providing examples for key and specifying that value can be any text, which goes beyond the schema's basic descriptions.

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

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

Description clearly states verb 'save' and resource 'data for reuse'. It distinguishes from sibling tools 'recall' and 'forget' by explicitly naming them and their roles.

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: 'when you discover something worth carrying forward'. Mentions scoping and persistence differences based on authentication. References siblings for retrieval and deletion.

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

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

Annotations already indicate readOnlyHint, idempotentHint, etc., and the description adds useful context: it cascades through multiple lookup endpoints internally, and explains return fields (ticker, CIK, company_name, RxCUI, etc.) with citation URIs. No contradictions with annotations.

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

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

Description is front-loaded with actionable examples and structured by entity type. It is slightly lengthy but each sentence adds value (e.g., replacing 2-3 lookups). Efficient for the complexity covered.

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 handles two entity types with multiple return fields and no output schema, the description adequately covers input usage, return details, and internal behavior. It addresses the agent's need to select and invoke the tool correctly.

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

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

Schema coverage is 100%, baseline 3. Description adds value by contextualizing values: for 'type' it lists enum values and their meaning, for 'value' it provides concrete examples (ticker, CIK, name; brand/generic names) and mentions auto-disambiguation for company, enriching beyond schema descriptions.

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

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

Description clearly specifies the tool resolves user-spoken names to canonical identifiers, with examples like 'ticker for...' and 'find the CIK for...'. It lists supported entity types (company, drug) with detailed return values, distinguishing it from sibling tools like ask_pipeworx or search_within which handle different tasks.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID', providing clear when-to-use guidance. While it does not explicitly mention when not to use or list alternatives, the context from sibling tools implies alternatives exist for other purposes.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is clear. The description adds behavioral details: it calls ai_visibility_check internally, ranks results, and surfaces the most/least recognized entity. 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 four sentences long, front-loaded with the core action and purpose, followed by method details and a concrete example. Every sentence adds value; no redundant or irrelevant 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 has no output schema, so the description compensates by describing the return format (ranked list with score, confidence, signal density). It explains internal composition (calling ai_visibility_check) and constraints (first entity as subject). Could mention limits on entity count or error behavior, but overall adequate.

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

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

Schema coverage is 100% (all four parameters have descriptions). The description adds context beyond the schema: it explains that the first entity is treated as the 'subject' for narrative, and that results are ranked with score, confidence, and signal density. This adds meaningful guidance for parameter selection.

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

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

The description uses specific verbs ('Compare', 'Probes', 'ranks', 'surfaces') and resources ('AI visibility across multiple entities'). It clearly distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic) by stating it performs a competitive audit with ranking.

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 concrete use case ('competitive AI-marketing audits') and an example question. It implies when to use (comparing multiple brands) but does not explicitly state when not to use or name alternatives, though the sibling context makes distinctions 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 declare readOnly, idempotent, non-destructive, and the description adds context about external service calls, partial failures (bundlephobia timeout 5-30s), graceful degradation with sources_failed, and full list of returned fields, all beyond the annotations.

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

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

Description is front-loaded with purpose and composite nature, then usage, return fields, limitations, and failure behavior. Every sentence adds unique value without redundancy.

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

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

Despite having no output schema, the description comprehensively lists all return fields (summary block, advisories, links, alternatives) and covers limitations, partial failure, and ecosystem scope, making the tool's behavior fully predictable.

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%. The description does not add new information about parameters beyond what is already in the schema (package name, version, defaults).

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

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

The description explicitly states the tool is a composite check for evaluating npm packages, combining deps.dev and bundlephobia data, and distinguishes it from siblings by specifying NPM-only scope and naming fallback tools for other ecosystems.

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

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

Provides explicit use cases ('is X safe / popular / small', 'what does adding lodash cost me'), states NPM-only limitation, and mentions that PyPI/Maven/etc. are handled differently 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds that the API is keyless (no authentication needed), results are newest-first, and keyword filtering is client-side. It could better explain the scan vs. return behavior implied by the limit parameter, but overall provides useful behavioral context beyond annotations.

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

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

The description is concise (two sentences) and front-loads the core purpose. The important note about no server-side keyword filtering is placed at the end. It could be slightly more structured, but it contains no wasted words.

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

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

The description covers the core behavior and parameters well, but lacks explanation of the return format or error handling. Given that there is no output schema and the tool has 5 parameters, the description is adequate but not fully comprehensive for an agent to understand the complete response.

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 reiterates that date filters are optional and keyword is client-side, but does not add significant new semantics beyond what the schema already provides. It serves as a helpful summary but does not deepen understanding of 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 tool searches UK government procurement notices from Contracts Finder, specifying the data source (OCDS by Cabinet Office), notice types (open tenders + awarded contracts), and key behaviors (filter by stage, date range, newest-first). It distinguishes itself as the UK complement to EU tenders, providing a specific verb and resource.

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 indicates when to use the tool (searching UK procurement notices) and notes that it is keyless. It explains the lack of a server-side keyword filter and provides guidance on client-side filtering. However, it does not explicitly mention when not to use it or contrast with sibling tools like get_notice or recent_notices.

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 important behavioral details beyond the annotations: embedding model (BGE-base-en), window size (500-char overlapping), similarity metric (cosine), character cap (200K) with truncation flagging, and that passages include character offsets for verification. This adds significant value beyond the annotations which already indicate read-only, idempotent behavior.

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

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

The description is concise, front-loaded with the main purpose, and includes only essential information. It is well-structured with a clear separation between the core functionality, usage guidance, and technical details. Every sentence contributes to understanding the tool.

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

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

Given the lack of an output schema, the description adequately covers the return format (top-N passages with offsets and scores). It also explains truncation behavior and technical implementation. However, it does not mention error handling or pagination, which could be useful 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 coverage is 100%, so the baseline is high. The description adds value by clarifying the 'text' maximum length (200K chars), providing concrete examples for the 'query' parameter, and explaining the purpose of the tool in relation to the parameters. However, the 'limit' parameter is already well-documented in the schema.

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

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

The description clearly states the tool performs 'semantic search INSIDE a fetched record' and gives a specific use case for large documents. It distinguishes itself from siblings by mentioning pairing with ask_pipeworx_grounded and contrasting with other tools that might not provide passages with offsets.

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

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

The description explicitly states when to use the tool ('when the record is too big to cram into the prompt') and explains benefits (saves context, returns only relevant passages). It also provides a pairing suggestion with another tool, but does not explicitly list situations where the tool should not be used.

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=false and idempotentHint=true. The description adds details on subscription creation, return of ID, delivery channels, rate limits (10/day for SMS), webhook behavior with HMAC signing and auto-disable, all beyond what annotations provide.

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

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

The description is comprehensive but somewhat long. It is well-structured with bold headings for types and delivery channels. Could be slightly more concise, but every sentence earns its place.

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

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

Given the complexity of the tool (multiple subscription types, nested delivery options), the description covers all necessary aspects without an output schema. It mentions the return value and webhook secret handling, making it 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%, but the description enriches each parameter with examples and clarifies constraints (e.g., 'sponsor or condition required' for clinical_trial). This adds significant value beyond the bare schema.

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

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

The description uses the verb 'Create' and specifies the resource as 'proactive monitoring subscription'. It clearly distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe' which manage existing subscriptions.

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

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

It states the requirement for a Pipeworx OAuth account and explains the supported types with example scenarios. It does not explicitly list when not to use, but provides sufficient context for appropriate use.

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

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

Annotations already declare readOnly, idempotent, openWorld hints; description adds details about return format (category-bucketed example questions with tool+argument shape). 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 thorough but slightly long; however, it is front-loaded with key phrases and every sentence adds value.

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

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

Given full schema coverage and no output schema, the description sufficiently explains output nature and purpose, making it complete for a discovery tool.

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

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

Schema coverage is 100%; description expands on 'topic' by listing example values and explaining omission behavior, adding significant meaning beyond schema.

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

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

The description clearly states it's the onboarding entry point for learning what to ask Pipeworx, lists categories, and distinguishes from sibling tools like ask_pipeworx and entity_profile.

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 it ('Use this FIRST') and how to call it (no arguments or optional topic parameter), providing clear guidance.

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

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

Adds context beyond annotations: explains that the row is deactivated, not deleted, and that historical events remain available. Consistent with destructiveHint=false and readOnlyHint=false.

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, each providing distinct information: purpose + ownership, and behavioral effect. No wasted words.

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

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

For a simple mutation with one parameter and no output schema, the description covers the effect (deactivation) and persistence. Could mention return value but is otherwise complete.

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

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

Schema coverage is 100%, and the description repeats the schema's parameter info ('Subscription id (uuid) returned by subscribe'). No additional semantic value beyond the schema.

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

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

Clearly states it cancels a subscription by id, specifying the resource and action. The description distinguishes from subscribe but does not explicitly compare to siblings like list_subscriptions or recent_alerts.

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?

Implicitly tells when to use by mentioning ownership enforcement ('you can only cancel your own subscriptions'), but no explicit guidance on alternatives or when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral details: returns a verdict (confirmed, approximately_correct, refuted, inconclusive, unsupported), extracted structured form, actual value with pipeworx:// citation, and percent delta. It also mentions the data source (SEC EDGAR + XBRL). 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 moderately concise, with the core purpose front-loaded using natural-language triggers. It includes a brief list of verdicts and notes the replacement of sequential calls. While it is a bit longer than necessary, every sentence contributes useful information, and it avoids redundancy.

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

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

Given the tool has no output schema, the description adequately explains return values (verdict types, actual value, citation, delta). It also specifies the domain scope (company-financial claims) and data source. It could mention error handling or unsupported claim types, but overall it provides sufficient context for an AI agent to understand what the tool does and what to expect.

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

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

The only parameter, 'claim', is fully described in the input schema with a description and examples. Schema description coverage is 100%. The tool description does not add additional parameter information beyond what's in the schema, but the examples provided in the tool description (e.g., 'Apple's FY2024 revenue was $400 billion') add value beyond the schema's generic 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: natural-language claim verification against authoritative sources. It uses explicit verbs like 'fact check' and 'verify the claim that…', and distinguishes itself by specifying the domain (company-financial claims for public US companies) and highlighting that it replaces multiple sequential calls, setting it apart from sibling tools like deep_research or bet_research.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and scopes it to company-financial claims. It implies when not to use (other types of claims) but does not name alternative tools. The mention of replacing sequential calls provides context for when this tool is more efficient.

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