Oyez

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

Annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) are well-supported. The description adds behavioral context beyond annotations: cost implications (BYO key for Anthropic), model defaults, and return format. No contradictions; the description enriches understanding of tool behavior.

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

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

The description is two sentences, front-loaded with the core purpose and output format. Every word earns its place, with no redundancy or fluff. It efficiently conveys purpose, usage, and return 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?

Given no output schema, the description adequately covers the return format (per-model fields plus combined view), usage constraints (free default vs. paid Anthropic), and parameter details. It could mention response size limits or rate considerations, but overall it provides sufficient information for an AI agent to use the tool correctly.

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

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

Schema coverage is 100% with detailed descriptions for all four parameters. The description adds minimal extra value beyond the schema, mainly clarifying the default model for the 'models' parameter and the pass-through nature of '_apiKey'. This meets the baseline expectation for high-coverage schemas.

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

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

The description clearly states the tool's function: probe LLMs for knowledge about an entity and score visibility on a 0-100 scale. It uses specific verbs (probe, score) and resource (LLMs). Although the sibling list includes similar tools like 'ask_pipeworx', this tool's focus on multi-model visibility scoring distinguishes it effectively.

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 context on when to use ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model and optional Anthropic key usage. It does not explicitly exclude scenarios or contrast with alternatives, but the given guidelines are clear and actionable for an AI agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds that it routes to 3,899 tools and returns structured answers with citations, which provides useful operational 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 long but front-loaded with core purpose and usage guidance. Every sentence adds value, though some redundancy exists (e.g., listing domains twice). Slightly verbose but well-structured.

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

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

Fully explains the tool's role, inputs, outputs (structured citations), and differentiation from 30+ siblings. Despite no output schema, the description covers return format comprehensively. Parameters are thoroughly documented.

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

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

Schema has 100% coverage with 6 parameters all described as aliases for question. The description adds value by providing concrete examples of questions and explaining the kind of input expected, elevating it above the baseline of 3.

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

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

The description clearly states it answers factual questions about current/historical data, lists specific domains (SEC filings, FDA, etc.), and distinguishes from siblings like ask_pipeworx_grounded and deep_research. The verb 'ask' combined with the resource 'Pipeworx' conveys a precise purpose.

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 recommends preferring this over web search, provides example queries, and specifies when to use alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions). No ambiguity about 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?

Adds substantial context beyond annotations: extra LLM call cost, refusal reasons, return structure, and behavior constraints. No contradiction with annotations.

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

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

Every sentence adds value, front-loaded with purpose. Efficient description packing usage, behavior, return format, and cost in one paragraph.

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 routing, return shape, refusal reasons, and cost. No output schema but description compensates. Lacks mention of rate limits or pagination, but not critical for tool selection.

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

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

Schema coverage 100%; description doesn't elaborate on parameters but notes 'fills arguments' automatically. 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?

Definition is clear: 'Hallucination-resistant answer mode' with specific verb 'picks...fills...fetches...extracts'. Distinguishes from ask_pipeworx by emphasizing refusal mechanism and high-stakes use.

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 (quoted/cited/acted-on answers) and when not (casual lookups), and names alternative ask_pipeworx. Provides reasoning for preference.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds extensive behavioral details: fan-out examples, resolver contract, parent event extractor, news fields, safety mechanisms (low-confidence short-circuit, closed market skip), tradeability warnings, and resolution-rule risk. No contradictions.

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

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

Front-loaded with general purpose, then detailed examples and edge cases. While long, every sentence adds value. Could be slightly more concise, but structure is logical and well-organized.

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

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

Given the tool's complexity (classifiers, fan-out, response shapes), the description is highly complete. It covers all important aspects: matching, evidence, analysis, safety, error states. No output schema, but response shapes are described in detail.

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 three parameters are fully described in the schema (100% coverage). The description adds meaning: explains market input formats (slug, URL, question), depth values (quick vs thorough), and include_raw behavior (summarized vs full payloads with size estimates).

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 researches a Polymarket bet by pulling Pipeworx data, specifies input types (slug, URL, question text), and outlines what it does: resolve, classify, fan out, and return evidence. It distinguishes from siblings implicitly by focusing on single-bet research rather than arbitration or edge tracking.

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

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

Explicitly states use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It covers caveats like low-confidence matches and closed markets, but does not mention when not to use or alternative tools.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint, openWorldHint) already indicate safety and non-destructiveness. The description adds value by stating 'Keyless' (no authentication needed) and summarizing the return format with fields, which are not in annotations. No contradictions.

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

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

Two sentences, no extraneous words. Front-loaded with action and resource purpose. Perfectly concise for the information needed.

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

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

No output schema exists, so the description compensates by detailing return fields (name, docket, citation, short question, oyez_url). It also notes 'Keyless' as a usage context. For a simple list tool with strong annotations, this is complete but could mention pagination or ordering.

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 reiterates 'given term year' and 'compact summaries', adding no new syntactic or semantic detail beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'List', the resource 'SCOTUS cases', the parameter 'term year', and the output format 'compact summaries (name, docket, citation, short question, oyez_url)'. It distinguishes from siblings like 'get_case' and 'search_cases' by focusing on bulk listing for a full term.

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

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

The description says 'Use to browse a full term', which implies its usage context. However, it does not explicitly state when not to use it or provide alternatives from siblings (e.g., 'search_cases' for querying). Guidance is present but minimal.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description details what data is pulled for each type: company (10-K revenue, net income, etc.) and drug (FAERS counts, FDA approvals, trial counts). It also mentions correct handling of off-calendar fiscal years, sorting by primary metric, and citation URIs in output. No contradictions with annotations.

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

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

The description is a single dense paragraph, but it is front-loaded with key trigger phrases and purpose. Every sentence adds value, though a slight structure improvement (e.g., separating company vs drug details) could enhance readability.

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

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

Even without an output schema, the description adequately describes the return format: paired data, citation URIs, and sorted by primary metric. This provides sufficient context for an AI agent to understand the output.

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

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

With 100% schema description coverage, the description adds context: it explains the 'type' enum values and provides examples for 'values' (e.g., tickers/CIKs for company, drug names). It also states that results are sorted by primary metric, enhancing parameter understanding.

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

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

The description explicitly states 'side-by-side comparison of 2–5 companies or drugs' and provides trigger phrases like 'Compare X and Y'. It distinguishes itself from siblings like 'entity_profile' by noting that it replaces 8–15 sequential single-pack lookups.

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

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

The description gives clear guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also quantifies the efficiency gain by stating it replaces 8–15 sequential lookups.

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 behavioral traits beyond annotations: decomposition, parallel routing, output format (findings with evidence, confidence, gaps), time expectation (15-60s), and that it never invents. Annotations already cover read-only, open-world, idempotent; description adds rich context.

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

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

Description is comprehensive but somewhat verbose; however, it front-loads critical prerequisites and alternative tool. Structure is clear with contrasts and examples, but could be more concise.

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

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

Given no output schema, description thoroughly explains return format, prerequisites, behavioral notes, and caveats. Covers all necessary context for an agent to use the tool correctly.

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

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

Schema has 100% description coverage, but description adds meaning by explaining 'depth' enum values (quick=3, standard=5, thorough=8 facets) and that 'question' can be broad/multi-part. Adds 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 the tool performs grounded multi-source research across structured data sources, decomposing questions into facets and returning a findings packet. It distinguishes itself from sibling ask_pipeworx by specifying its scope and use case.

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 when to use (broad/multi-part questions over structured data) and when not to use (single lookup, breaking news), with alternative tool mentioned. Also states account requirement and 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 that results include full schemas with curated examples and are ready to call directly, which is useful behavioral context. 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 (about 100 words), front-loaded with purpose, and includes necessary context without waste. Every sentence serves a purpose, such as listing domains and advising when to use.

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 6 parameters with high description coverage, no output schema. The description covers purpose, usage, and return value well. It could mention result ordering or pagination, but overall it is thorough.

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

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

Schema coverage is 100%, with all parameters described. The description's mention of aliases and examples adds minimal new meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool helps find tools by describing data or tasks, with specific examples (e.g., SEC filings, FDA drugs). It distinguishes itself as a discovery tool to call first, contrasting with sibling tools that provide direct answers.

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

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

The description explicitly advises using this tool when browsing or discovering available tools, and to call it first when many tools exist. It does not explicitly state when not to use it or name alternative tools, but the context is clear.

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

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

Annotations indicate readOnly, openWorld, idempotent. Description adds details on parallel fan-out across SEC EDGAR, XBRL, USPTO, news, GLEIF, and discloses patent API sunset May 2025 soft-fail. 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?

Long but efficient; front-loaded with user query patterns, then detailed behavior. Every sentence provides distinct information, but could be slightly more streamlined.

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

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

Despite no output schema, description enumerates all return fields (CIK, filings, fundamentals, patents, news, LEI) with data sources and limitations. Comprehensive for a profile 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 already has high coverage (100%), so baseline 3. Description adds value by explaining ticker vs zero-padded CIK format and instructing to use resolve_entity for names.

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 'full cross-source profile of a US public company in ONE parallel call' with specific verb+resource. Differentiates from sibling piecemeal lookups by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and provides sample 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?

Explicitly says use for holistic 'Tell me about X' queries, prefers over chaining, and provides exclusion: 'Names not supported — use resolve_entity first if you only have a name.'

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

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

Annotations already mark destructiveHint=true and idempotentHint=true. The description adds context about clearing 'sensitive data', which goes beyond the annotations. It is consistent with annotations and adds slight behavioral nuance.

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

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

The description is extremely concise, consisting of two short sentences that convey purpose, usage, and pairing. 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 tool with one parameter and no output schema, the description is complete: it explains what it does, when to use it, and how it relates to siblings.

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

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

Schema coverage is 100% with the key parameter already described. The description does not add additional meaning beyond the schema, 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 explicitly states 'Delete a previously stored memory by key.' It clearly identifies the verb (delete) and resource (memory), distinguishing it from sibling tools 'remember' (store) and 'recall' (retrieve).

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

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

The description provides explicit usage scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' It also recommends pairing with siblings 'remember' and 'recall', offering clear guidance on when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which the description's behavior aligns with (fetching, extracting, emitting). The description adds context about the output being 'production-ready' and 'standard llms.txt markdown format,' and that it is a 'single text blob.' 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 three sentences: first states purpose and scope, second explains the process, third lists use cases. It is concise, front-loaded with key information, and every sentence adds 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?

Given no output schema, the description explains the output format ('single text blob ready to drop at site-root/llms.txt') and covers purpose, process, output format, and use cases. For a simple tool with 2 parameters, this is fully complete.

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

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

Schema description coverage is 100%, so both parameters (url, max_links) are well-documented in the schema. The description does not add significant new information about parameters beyond what the schema provides, earning a baseline score of 3.

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

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

The description clearly states the tool's purpose: 'Generate a production-ready llms.txt file for any URL' for AI crawlers. It specifies the verb (generate), resource (llms.txt file), and scope (any URL), effectively distinguishing it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which have related but different functions.

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 use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It provides clear context for when to use the tool, though it does not explicitly state when not to use it or name alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the agent knows it's a safe read operation. The description adds value by noting 'Keyless' (no API key required) and detailing the returned fields, providing context beyond the annotations.

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

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

The description is a single sentence that front-loads the purpose and uses a dash to list content. It is concise and well-structured, though slightly long. Every part 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?

Given the tool's simplicity (no output schema, 2 params, good annotations), the description is largely complete. It lists all major return fields. It does not mention error handling or rate limits, but those are less critical for a read-only, idempotent lookup tool.

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

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

Schema description coverage is 100%, so the two parameters are already documented. The description confirms they are used 'by term and docket number' but adds no additional meaning or format details beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb 'Get' and resource 'full SCOTUS case from Oyez', and lists the exact content (e.g., question presented, facts, conclusion, justices, advocates). It clearly distinguishes from siblings like 'search_cases' by requiring a term and docket number for a complete case.

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

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

No explicit guidance on when to use this tool versus alternatives (e.g., 'search_cases' or 'cases_by_term'). The description implies a specific lookup use case but does not mention when not to use it or suggest other tools for broader queries.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds value by specifying that it returns only active subscriptions by default and lists the exact fields returned, enhancing behavioral understanding beyond annotations.

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

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

Two concise sentences. The first sentence provides the core functionality and return fields. The second sentence gives usage guidance. No unnecessary words, and the structure 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 simple input schema (one optional parameter), comprehensive annotations, and no output schema, the description covers all necessary aspects: what it does, what it returns, and when to use it. It is complete for an agent to effectively invoke the tool.

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

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

Schema coverage is 100% with the parameter fully described. The description does not explicitly mention the parameter but implies its effect by referring to 'active subscriptions.' While it doesn't add extra semantics, it also doesn't contradict 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 lists the caller's active subscriptions and specifies the returned fields. It distinguishes from siblings like 'subscribe' and 'unsubscribe' by stating usage 'before adding more or to find an id to cancel.'

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

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

Provides explicit guidance on when to use: to review current subscriptions before adding more or to find an ID for cancellation. This implicitly advises against using it when the goal is to subscribe or unsubscribe.

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

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

Annotations are neutral; description adds important behavioral details: rate-limited to 5/day/identifier, free, no quota impact, team reads digests daily, signal affects roadmap.

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, front-loaded with verb and purpose, no redundant information; every sentence earns its place.

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

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

Given no output schema, description fully covers usage, parameters, and behavior; no gaps for a feedback 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%, but description adds value by specifying typical message length (1-2 sentences, 2000 chars max) and clarifying type categories beyond enum descriptions.

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

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

The description clearly states the tool sends feedback about bugs, missing features, or praise to the Pipeworx team, distinguishing it from sibling tools which are mostly query or research 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 specifies when to use (bug, feature, data_gap, praise) and what to avoid (pasting end-user prompt), plus mentions rate limits and quota exemption.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds value by explaining the data source (CF analytics-engine), no PII, and caching behavior (5min-1h). This goes beyond the annotations without contradicting them.

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

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

The description is concise with 4 sentences, each contributing value. It is front-loaded with the core function, then provides use cases, and ends with technical details. No redundant or filler content.

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

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

For a simple read-only tool with one parameter and high annotation coverage, the description is complete. It explains aggregation, caching, PII, and provides use cases. No output schema is needed given the simplicity.

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

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

Schema coverage is 100% with a single parameter (window) that has an enum and description. The description adds meaningful context about how shorter vs longer windows affect results (hot vs steady-state demand), which supplements the schema.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a window. It uses specific verbs ('returns', 'discovering', 'confirming', 'seeing') and distinguishes from sibling tools by focusing on trending data rather than search or other functions.

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, providing clear guidance on when to use this tool. It does not explicitly state when not to use it, but the context and sibling list imply alternatives. It could be improved by mentioning situations where it's not appropriate, but the given guidance is strong.

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

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

Annotations indicate read-only, open world, idempotent, non-destructive behavior. The description goes far beyond with algorithmic details (Jaccard similarity, partition filter, fill check against live CLOB depth) and a warning about not trading when realizable edge is ≤0. 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 and front-loaded with the requirement and purpose. Every sentence provides value, covering modes, algorithmic details, response structure, and fill check. No fluff or repetition.

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

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

Given the complexity and lack of output schema, the description adequately explains the response structure (`opportunities[]`, `partition_check`), the algorithms, and the fill check. It covers prerequisites and modes. Minor omission: no explicit error handling for invalid slugs or topics.

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 `event` and `topic`. The description adds significant meaning: examples of event slugs, explanation that event mode walks child markets, and topic mode searches related events. This enhances the schema's baseline information.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between single-event (`event`) and cross-event (`topic`) modes, and is distinct 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 explicitly requires one of `event` or `topic`, recommends `event` for specific markets and `topic` for cross-event scanning, and explains when each mode is appropriate. It does not explicitly exclude other tools or list negative cases, but provides clear context for 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?

Discloses caching behavior (1h at KV level), internal model families, structural arbitrage logic, concentrated longshot rare-by-design nature, and diagnostics for empty segments. Annotations already indicate readOnly and idempotent, but description adds significant 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?

Description is long but well-structured with clear sections (SEGMENTS, EVERY OPPORTUNITY, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). Front-loaded with core purpose. Every sentence adds value for the complex tool, though slightly verbose for simpler use cases.

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 logic, description is fully complete: explains output structure (by_segment, diagnostics), edge calculation, Kelly fractions, liquidity/spread warning, 24h move alert, Fed handling, and filter skip diagnostics. No gaps remain.

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

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

Despite 100% schema coverage, description adds substantial meaning: explains each knob's purpose, recommended values, interactions (e.g., min_partition_leg_kelly for partition arbs, min_liquidity for thin-book dropping), and trade-off guidance. Goes far beyond the schema descriptions.

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

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

Clearly states tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. Distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on edge discovery without paging.

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

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

Provides clear context for daily betting opportunity discovery and explains when to use it (no manual paging). Mentions Fed bets surface here but are excluded from ranking, giving a when-not-to-use nuance. However, lacks explicit comparison to sibling tools or alternative usage scenarios.

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

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

Beyond the annotations (read-only, non-destructive), the description adds significant behavioral context: history bounded by 60-day TTL, snapshots written on cache-miss, decay numbers based on daily closes net of default slippage (not intraday), and gaps in snapshot dates due to cache-miss days. 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 well-structured: it starts with the core purpose, then details the output sections (tracked, expired, snapshot_dates) and limits. While somewhat verbose, every sentence adds necessary context. It is front-loaded and logically organized, though could be slightly more terse.

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

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

Given that there is no output schema, the description fully explains the return format: tracked array with fields (edge_pp_net time-series, first_seen, trend, decay_pp_per_day), expired array with lifespan_days, and snapshot_dates. It also covers limits (60-day TTL, granularity). This is complete for the tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining how parameters affect analysis (e.g., 'days' limits lookback to 30, 'window' determines snapshot family) and by providing real-world context (e.g., 'default 14, max 30'). This clarifies the parameters' role beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from polymarket_edges snapshots. It answers a specific analytical question ('how long has this edge existed and is it shrinking?') and differentiates from the sibling tool 'polymarket_edges' by focusing on temporal dynamics rather than current values.

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

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

The description provides clear context on when to use the tool (to distinguish fresh vs. aged edges) but does not explicitly state when not to use it or name alternatives among siblings. The contrast between 'a fresh wide edge and a 3-week-old wide edge' implies a specific use case, but explicit guidance on exclusion is missing.

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

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

The description goes beyond annotations (which indicate read-only and idempotent) by detailing the behavior: walking the order book ladder, returning specific fields like slippage_pp, verdict, and thin_legs, and explaining forced directional risk. No contradiction with annotations.

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

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

The description is relatively long but well-structured with mode-specific sections and bullet-like formatting. Every sentence adds value given the tool's complexity, though slight trimming could improve conciseness.

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

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

With no output schema, the description thoroughly explains return values for both modes, behavioral risks (partial fill, directional exposure), and constraints (size clamp). This fully compensates for the lack of output schema and covers all needed context.

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

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

Schema coverage is 100% (baseline 3), but the description adds significant meaning: it explains size_usd interpretation per mode (max spend vs target proceeds vs settlement notional), default values, and clamps, justifying a 4.

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

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

The description clearly states the tool checks realizable vs theoretical edge against live CLOB order-book depth. It distinguishes between single-market and basket modes and explicitly connects to sibling tools like polymarket_arbitrage and polymarket_edges, making purpose and differentiation very clear.

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

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

The description explicitly says to use before acting on polymarket_arbitrage signals or trades above $500, and it provides separate guidance for single-market and basket modes, including warnings about partial basket fills leading to unhedged positions.

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

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

The description adds extensive behavioral details beyond annotations: explains compatibility_warning, temporal_alignment, skipped_cross_type, and response format. It aligns with readOnlyHint (read operation) and provides safety fields that prevent misinterpretation.

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

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

The description is well-structured with a summary, modes, response, and safety fields. It is front-loaded but verbose; each sentence provides value for a complex tool.

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

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

Without an output schema, the description adequately explains return values (leg-by-leg prices, top_spreads_pp) and safety fields. It covers parameters, modes, and limitations, making it complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions, and the description adds extra meaning: lists topic values, explains overriding behavior, and details how parameters interact. It also clarifies that many topics yield no tradable spread.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies two modes (topic shortcuts and explicit tickers) and distinguishes itself from sibling tools focused on single-venue analysis or other polymarket tools.

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

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

The description explains when to use each mode and warns that most pre-mapped topics return compatibility warnings, setting realistic expectations. It does not explicitly compare with sibling tools but provides enough context for an agent to decide.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by explaining scoping (to identifier) and pairing with related tools. It does not contradict any annotations and provides additional context about how the tool behaves (e.g., listing all keys when no key argument is provided).

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

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

The description is extremely concise—two sentences that front-load the core action (retrieve or list) and then provide usage guidance, examples, and scope. Every sentence adds value and there is no redundancy. It is well-structured and easy to scan.

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

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

Given the tool has only one optional parameter, no output schema, and annotations covering safety, the description is fully complete. It explains the main functionality, when to use it, what to expect, how it is scoped, and how it relates to sibling tools. No additional information is needed for an agent to use it correctly.

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

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

Schema coverage is 100% for the single parameter 'key'. The description adds meaningful context beyond the schema: it specifies that omitting the key lists all saved keys, and it gives examples of the kinds of values that might be stored (ticker, address, notes). This helps the agent understand how to use the parameter effectively.

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 specific verb 'retrieve' and clearly identifies the resource (a value saved via remember). It also distinguishes the tool from its siblings (remember, forget) by indicating that this tool retrieves or lists, while the others save or delete. The examples of ticker, address, notes further clarify the purpose.

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

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

The description explains when to use the tool: 'to look up context the agent stored earlier'. It provides concrete examples (target ticker, address, research notes) and implies that for saving or deleting, the paired tools (remember/forget) should be used. It lacks an explicit 'when not to use' statement but the guidance is clear enough.

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

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

The description states that setting mark_read:true flags events as read, modifying state. However, annotations declare readOnlyHint=true, indicating no state modification. This is a direct contradiction. The description is transparent about the behavior, but it conflicts with the provided annotations, leading to a low score.

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

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

The description is concise yet comprehensive, with no wasted words. It efficiently conveys the tool's purpose, key behaviors, parameters, and alternative access method in a single paragraph. The most critical 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 absence of an output schema, the description adequately details return fields (source, citation_uri, raw payload). It also covers polling behavior and an alternative HTTP endpoint. For a tool with five optional parameters, this is fairly complete, though pagination details are missing.

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

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

All parameters have schema descriptions (100% coverage), but the description adds significant value by explaining usage patterns (e.g., filtering by ISO timestamp, example type 'sec_8k', mark_read's effect on subsequent calls). This goes beyond mere repetition of schema fields, enhancing 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 specifies the tool's function: pulling fired events from the subscription feed. It distinguishes itself from siblings by focusing on retrieving alerts rather than managing subscriptions, and provides concrete details about returned fields (source, citation_uri, raw payload). The verb 'pull' and resource 'alerts' are 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 provides clear usage context: polling is acceptable, and an alternative HTTP endpoint is mentioned for scripts/dashboards. It explains filtering options (type, since) and the mark_read functionality. While it doesn't explicitly state when not to use the tool, the guidance is sufficient for most scenarios.

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

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

Discloses multiple data sources (SEC EDGAR, GDELT→GNews fallback, USPTO), API limitations, and return structure. This adds significant context beyond the readOnlyHint annotation.

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

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

Packed with value but front-loaded with example queries. Every sentence earns its place, though slightly long.

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

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

For a complex tool with multiple data sources and fallback logic, the description covers all behavioral aspects and return structure despite no output schema.

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

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

Schema coverage is 100%, so baseline is 3. Description adds useful details: 'value' accepts ticker or CIK, 'since' examples, and 'type' limited to company.

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 provides a change feed for a company in a specified time window, aggregating filings, news, and patents. Distinguishes from sibling 'entity_profile' which provides static 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?

Provides explicit example queries and contrasts with 'entity_profile' for static profile queries, telling when to use alternative.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. Description adds session scoping, persistence differences (authenticated vs anonymous, 24-hour retention). 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 concise with 4 sentences covering purpose, usage, scope, and pairing with siblings. Each sentence adds value; no fluff.

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

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

No output schema, but description adequately covers write operation, pairing with retrieval/deletion tools, and retention rules. Sufficient for the agent to understand usage.

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

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

Schema covers both parameters with 100% description (key and value). Description adds example formats like 'subject_property' but doesn't significantly extend beyond schema. Baseline 3 applies.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It distinguishes itself from sibling tools like 'forget' and 'recall', making it unique.

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

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

Explicit guidance on when to use: 'when you discover something worth carrying forward'. It also references sibling tools 'recall' and 'forget' for later retrieval/deletion, though doesn't mention 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 indicate read-only, idempotent, open-world. The description adds that internal cascading lookups occur and provides output details (e.g., citation URIs). It does not mention error handling but is otherwise transparent.

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

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

The description is a single, well-structured paragraph that front-loads the core purpose, uses examples, and lists supported types concisely. Every sentence adds 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?

Given no output schema, the description fully explains return values for both entity types, including citation URIs. It covers input formats and behavior context (cascading lookups), making it complete for agent use.

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

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

Schema coverage is 100%, and the description enriches both parameters: for 'type' it lists enum values with context; for 'value' it gives examples and acceptable formats. Output descriptions are also provided, 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 that the tool resolves a user-spoken name to a canonical identifier, with examples like 'What's the ticker for...' and explicit mention of supported types (company, drug). It distinguishes from siblings by being the primary ID lookup tool.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing a strong usage directive. It also notes that it replaces multiple manual lookups, implying efficiency.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false, so the safety profile is clear. The description adds that it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, signal density, but does not reveal additional behavioral traits (e.g., rate limits, data sources) 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 two concise sentences followed by an example and return format note. It is front-loaded with the main action and purpose. Every sentence adds value, though the example could be integrated into the first sentence for even greater conciseness.

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

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

The tool has no output schema, so the description correctly includes the return format ('ranked list with score, confidence, signal density per entity'). It explains the process (probing ai_visibility_check) and provides a use case. However, it does not mention any limitations (e.g., entity count range is in schema, not description) or error handling.

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 input schema already documents all parameters. The tool's description does not add any additional meaning beyond the schema; it only mentions 'Probes each entity' which is implicit. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: to compare AI visibility across multiple entities side-by-side. It specifies probing each entity with ai_visibility_check, ranking by score, and surfacing most/least recognized. The concrete example ('does Claude know about us as well as our competitors?') and distinction from sibling ai_visibility_check (single entity) make 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?

The description explicitly states it is 'useful for competitive AI-marketing audits' and implies multi-entity comparison, differentiating it from the single-entity sibling ai_visibility_check. However, it does not explicitly state when not to use it or mention alternatives like compare_entities, which would have earned a 5.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds latency note (5-30s for new versions) and graceful degradation with sources_failed. No contradictions.

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

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

Two coherent paragraphs with key info front-loaded. First sentence is slightly long but packs essential details. No wasted words.

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

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

With no output schema, the description enumerates return fields (summary block, advisories, links, versions) and covers partial failure edge case, making it fully informative.

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?

Both parameters are described in schema (100% coverage). Description adds context for scoped packages and default version behavior, providing additional clarity 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?

Describes a composite check for npm packages, specifying the sources (deps.dev, bundlephobia) and what it returns. Clearly distinguishes from sibling search tools by being package-specific.

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

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

Explicitly states when to use (e.g., 'is X safe / popular / small') and notes npm-only limitation. Missing explicit 'when not to use' for non-npm, but guidance is strong overall.

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, etc. The description adds behavioral context: returns compact summaries with question, description, and IDs for get_case, plus 'Keyless' indicating no authentication required. No contradictions.

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

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

Two sentences, front-loaded with main purpose, no redundant information. 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 3 optional parameters and no output schema, the description covers return format, default behavior, and keyless access. Adequate for a search tool.

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

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

Schema coverage is 100%. Description adds semantics: 'filtered client-side' for name and provides examples (e.g., 'Harvard'), clarifying the substring matching behavior.

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 (Search), resource (US Supreme Court cases from Oyez), and scope (by term year and/or case-name substring). It also mentions the return format and distinguishes from siblings like get_case.

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 usage guidance: defaults to most recent term if no parameters given, and mentions 'Keyless' indicating no API key needed. However, it does not explicitly state when to choose this over siblings like cases_by_term.

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. The description adds specific technical details: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation flagging, and return of offsets and scores. 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 well-structured and informative, but slightly lengthy. Every sentence serves a purpose—explaining functionality, use case, technical details, and pairing—so it earns its length.

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

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

Given no output schema, the description explains return values (passages with offsets and scores) and covers truncation. It addresses edge cases and provides pairing advice, making it complete for an agent to use effectively.

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

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

Schema coverage is 100%, so baseline 3. Description enriches each parameter: text gets context on max size and truncation, query gets natural-language examples, limit gets default value. Adds meaningful usage context 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 the tool does semantic search inside a fetched record, using specific examples (SEC 10-K, article) and distinguishing from siblings like ask_pipeworx_grounded by focusing on already-pulled text and returning 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?

Explicitly advises use when a record is too large for the prompt, and mentions pairing with ask_pipeworx_grounded for grounded results. Lacks explicit 'when not to use' statements, but the context is clear enough for an AI agent.

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

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

Annotations indicate readOnlyHint=false and idempotentHint=true. The description adds behavioral context beyond annotations: it explains the need for an OAuth account, persistence, delivery specifics (SMS cap, webhook auto-disabling), and that the subscription is always-on with a feed pull. No contradictions.

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

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

The description is dense but well-organized, covering purpose, requirements, type examples, and delivery options in a logical flow. It is not overly verbose, though it could be slightly refined for brevity without losing clarity.

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

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

Given the complexity (multiple types, nested delivery object, no output schema), the description is remarkably complete: it describes the return value, type-specific parameters, delivery options with constraints (e.g., SMS cap, phone verification, webhook HMAC), and even error conditions. This ensures an agent can correctly invoke the tool.

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

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

All parameters are documented in the schema (100% coverage), but the description adds significant value by providing concrete examples for each type (e.g., sec_8k with items:['5.02']) and detailed delivery constraints (e.g., phone must be verified, webhook HMAC signing). This goes well beyond the schema descriptions.

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

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

The description clearly states the action ('Create a proactive monitoring subscription') and the resource ('live-data event stream'). It specifies the return value ('Returns the new subscription id'), distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides context on requirements ('Requires a Pipeworx OAuth account'), supported types with examples, and delivery channel constraints (e.g., phone verification, 10/day SMS cap). It implicitly guides when to use this tool, though 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 declare read-only, idempotent, and open-world hints. The description adds behavioral context: it returns live-curated examples with exact tool calls, and explains the output structure. No contradictions.

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

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

The description is a single well-structured paragraph that front-loads the purpose, uses bullet points effectively for categories, and has no extraneous information. 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?

Despite lacking an output schema, the description fully explains what the tool returns (category-bucketed questions with tool+argument shapes) and when to use it. It covers usage, output, and context completely.

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

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

The schema has 100% coverage for the single optional parameter. The description adds specific topic values (finance, pharma, etc.) and clarifies the default behavior when omitted, adding significant value.

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 is an onboarding entry point that returns categorized example questions with tool/argument shapes. It distinguishes itself from sibling tools like ask_pipeworx and discover_tools by specifying its role as a first-stop for exploring capabilities.

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 this FIRST when you do not yet know what Pipeworx can do for you' and explains how to use it with/without the topic parameter. It lacks explicit 'when not to use' but the context is strong enough to infer alternatives.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds valuable behavioral context: ownership enforcement and deactivation (not deletion), plus the ability to retain historical events via recent_alerts. This goes beyond the annotations.

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

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

Two sentences, front-loaded with the core purpose, followed by constraints and effects. No redundant words; 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 single-parameter tool with full annotation and schema coverage, the description provides complete context: action, ownership, persistence behavior, and linkage to another tool (recent_alerts). No gaps evident.

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

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

The input schema has 100% coverage, describing `id` as 'Subscription id (uuid) returned by subscribe'. The description does not add additional parameter semantics beyond 'by id'. Baseline score of 3 is appropriate since schema carries the weight.

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 'Cancel a subscription by id' with a specific verb and resource. It distinguishes from siblings like `subscribe` and `list_subscriptions` by specifying the action and the effect, deactivation rather than deletion.

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 'Ownership is enforced — you can only cancel your own subscriptions', which provides clear context for when to use the tool. It does not explicitly state when not to use it, but the sibling names and the effect clarify alternatives.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it returns a verdict, structured form, actual value with citation, and percent delta, and mentions the underlying sources (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 reasonably concise and well-structured. It starts with example query patterns, then states the usage context, and provides details about the return values and scope. Every part adds value, though it could be slightly more concise by trimming redundant phrases.

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

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

Given only one parameter and no output schema, the description is very complete. It explains the return fields (verdict, structured form, actual value, citation, delta) and explicitly states scope limitations (v1 supports company-financial claims). This provides sufficient context for an agent to understand 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?

There is only one parameter 'claim' with a clear schema description. The tool's description adds significant value by providing natural-language examples and clarifying the type of claims supported (company-financial). Since schema coverage is 100%, the baseline is 3, but the description elevates it.

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

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

The description clearly states the tool's function: natural-language claim verification against authoritative sources. It uses specific verbs like 'validate', 'verify', 'confirm or refute', and identifies the resource as claims. The tool is well-distinguished from siblings by noting it replaces multiple sequential calls.

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

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

The description explicitly guides usage: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies the current scope (company-financial claims) and provides example query patterns. However, it doesn't explicitly mention when not to use or suggest alternatives, which prevents a higher score.

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