patents

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

Annotations already declare readOnlyHint and idempotentHint. Description adds cost context (free default, BYO key for Anthropic) and return format, going 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?

Three sentences with no redundancy. Core function, options, and output all covered efficiently.

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

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

Describes return per-model and combined view despite no output schema. Covers all 4 parameters adequately for a tool of this 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%, but description adds value by providing examples (e.g., 'Pipeworx', 'B2B SaaS') and explaining the role of _apiKey in routing to Anthropic.

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?

Uses specific verb 'probe' and clear resource 'LLMs for business/brand visibility'. Differentiates from siblings like ask_pipeworx or bet_research by focusing on multi-model visibility scoring.

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

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

Explicitly mentions use cases (AI-marketing audits, pre-launch checks, competitive monitoring) and explains optional parameters. Lacks explicit alternatives but 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 already indicate read-only, open-world, idempotent, and non-destructive. The description adds context by detailing that the tool routes to 4,774 tools across 1,242 sources and returns structured answers with pipeworx:// citation URIs. It does not contradict annotations.

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

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

The description is relatively long but well-structured, starting with the key preference statement. Every sentence provides useful information, though minor trimming could improve conciseness. The examples are helpful.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It covers purpose, usage, alternatives, and return format (structured answer with citations). It adequately prepares an AI agent for correct invocation.

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

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

Schema coverage is 100%, with all parameters well described. The description adds value by providing example questions that illustrate parameter usage, and it hints at the breadth of questions the tool can handle. This goes beyond the schema's parameter descriptions.

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

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

The description clearly states the tool's function: routing questions to a vast array of tools/sources and returning structured answers with citations. It explicitly prefers this over web search and lists numerous specific use cases, distinguishing it from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description provides explicit guidance on when to use this tool (most factual questions) versus alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions). It also includes concrete examples like 'current US unemployment rate' and 'Apple's latest 10-K'.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive. The description adds significant behavioral context: it routes through many tools, fills arguments, fetches data, and extracts answers only from tool content, returning explicit refusal reasons on failure. No contradiction with annotations.

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

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

Description is relatively long but pack with essential details: behavior, use cases, return structure, refusal reasons, and cost trade-off. Every sentence adds value, though could potentially be shortened without losing clarity. Front-loads key behavior.

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

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

Despite no output schema, the description fully explains the return structure (answer, evidence, confidence, source, fetched_at, refusal_reason) and all possible refusal reasons. Works well with annotations to give a complete picture of tool behavior.

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

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

The input schema has 6 parameters all aliases for 'question', with 100% description coverage. The description adds no additional parameter meaning beyond stating the question is in natural language. Baseline of 3 is appropriate as the schema already fully documents the parameters.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode for high-stakes reads that routes to the right tool and extracts answers only from tool results. It explicitly distinguishes from the sibling 'ask_pipeworx' by detailing the extraction process and return structure.

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 (high-stakes reads where facts must be accurate) and when not to (casual lookups, prefer ask_pipeworx). Also mentions cost trade-off (one extra LLM call). Provides clear decision criteria.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details: resolution confidence, parent event extraction, news fallback, safety on low confidence, closed market handling, wide spread warnings, cancellation rule parsing. No contradiction with annotations.

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

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

The description is very long (multiple paragraphs) but well-organized with sections like CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES. While structured, it could be more concise; every sentence adds value but some details could be summarized.

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, schema covers parameters, and there is no output schema, the description thoroughly explains response shapes, resolution matching, parent event, news fields, safety mechanisms, and cancellation rules. It is complete for an agent to understand inputs, outputs, and edge cases.

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

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

Schema coverage is 100%, but the description adds significant meaning: explains market parameter accepts slug, URL, or question text; depth parameter has 'quick' vs 'thorough' behavior; include_raw parameter summarizes vs full payloads. This goes well above baseline.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and use cases ('should I bet on X', 'what does the data say about Y'). It distinguishes from sibling tools by focusing on betting research with a specific pipeline.

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

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

The description explicitly lists when to use the tool with examples like 'should I bet on X' and 'is there edge in Z'. It does not explicitly state when not to use it or mention alternatives, but the use cases are clear and specific enough to guide an agent.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description details specific behaviors: handles off-calendar fiscal years for companies, pulls different data for company vs. drug, sorts results by primary metric, returns paired data with citation URIs. No contradictions with annotations.

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

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

The description is well-structured and front-loaded with examples and purpose. While it is relatively long, every sentence adds value and it avoids fluff. Could be slightly more concise, but still effective.

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 explains what data is returned (revenue, net income, etc. for company; adverse events, approvals, trials for drug) and that it includes citation URIs. It covers edge cases like fiscal year handling and replaces many lookups.

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 but description adds significant meaning: for type='company', it explains data source (SEC EDGAR/XBRL, latest 10-K data) and metrics; for type='drug', it explains FAERS counts, FDA approvals, trials. For values, it specifies tickers/CIKs for companies, drug names for drugs.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one call, with specific examples and explicit preference over sequential lookups. It distinguishes from sibling tools like entity_profile and ask_pipeworx.

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

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

The description gives explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and shows the query patterns (e.g., 'compare X and Y'). It clearly indicates when to use this tool over alternatives.

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

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

Annotated as read-only, idempotent, non-destructive. Description adds: not open-web search, parallel decomposition, 15-60s latency, paid plan for thorough, gaps[] for unanswered facets. 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?

Slightly long but every sentence adds unique value (prerequisites, comparison, behavior, expectations). Front-loaded with critical usage warning. Could trim some redundancy but justified given complexity.

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

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

No output schema, but description fully explains return format (evidence, confidence, source, time, citation, gaps[]), scope, latency, error cases, and prerequisites. Leaves no major questions unanswered.

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

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

Schema covers 100% of parameters. Description adds context: 'depth:"thorough" needs a paid plan' and clarifies that question should be natural language. Slightly above baseline but schema already does most of the work.

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

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

Clearly states it performs 'grounded multi-source research across Pipeworx's 1242 STRUCTURED data sources' and contrasts with siblings like ask_pipeworx (single lookup) and current-news tools. Unique verbs: 'decomposes, routes, returns'.

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 (broad/multi-part structured questions) and when not (single lookup → ask_pipeworx, breaking news → ask_pipeworx). Also provides account requirements and fallback if not signed in.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds value by detailing that results include full input schemas with curated examples and are 'ready to call directly,' which goes beyond the annotation hints.

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

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

Description is front-loaded with purpose and usage, then delivers specifics on return format and timing. Every sentence serves a purpose, though it could be slightly more concise by removing redundancy (e.g., the domain list is lengthy but helpful).

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 compensates by explaining the return format (top-N tools with names, descriptions, and schemas). It also covers parameter aliases, making the tool self-contained. Slight gap: no mention of error handling or empty results.

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

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

Schema coverage is 100%, but the description adds meaning by listing multiple aliases for the query parameter (task, q, description, search) and providing concrete examples like 'analyze housing market trends', which clarifies parameter usage beyond the schema's brief descriptions.

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

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

Description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses a specific verb (find/discover) and resource (tools), distinguishing it from sibling tools like search_inventors or search_patents that search within data rather than for tools.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear guidance on when to use 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. The description adds value by detailing the parallel fan-out, specific return fields, and the soft-fail on patents. 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 information-dense but front-loaded with trigger phrases. Every sentence contributes value, though it could be slightly more compact. It avoids unnecessary words.

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

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

Given the rich schema and annotations, the description covers all needed context: input format, return fields, limitations (name support, patent sunset), and even the multi-source fan-out. No output schema, but the description compensates by listing what is returned.

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

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

Schema coverage is 100%, but the description adds concrete examples (e.g., 'AAPL', '0000320193') and clarifies that names are not supported. This goes beyond the schema's enum description for type and the value example.

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

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

The description opens with concrete example queries ('Tell me about X', 'research Acme') then states the precise action: 'full cross-source profile of a US public company in ONE parallel call.' It lists specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and return fields, clearly differentiating from sibling tools like resolve_entity and chaining 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?

Explicit usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives a direct alternative: 'use resolve_entity first if you only have a name.' This tells the agent when and when not to use the tool.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data and that memory was previously stored. Does not contradict annotations.

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

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

Three sentences, each adding value: action, usage context, related tools. No filler.

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

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

For a simple tool with one parameter and no output schema, description covers purpose, usage, and sibling relationships. Could mention return value or error handling, but not required.

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

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

Schema covers the single parameter 'key' with description 'Memory key to delete', which is sufficient. Description does not add additional meaning beyond what schema provides.

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

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

Clearly states 'Delete a previously stored memory by key'. The verb 'delete' and resource 'memory' are specific. Mention of pairing with 'remember' and 'recall' distinguishes it from siblings.

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

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

Explicitly provides three use cases: stale context, task completion, clearing sensitive data. Also directs to pair with remember and recall, indicating alternatives.

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

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

Discloses internal steps (fetch, extract, emit) and output format beyond annotations. Annotations already indicate read-only, idempotent, non-destructive; description adds process detail without contradiction.

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

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

Three sentences, front-loaded with purpose and output. Every sentence adds value; no wasted words.

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

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

With only two simple parameters and no output schema, the description fully covers the tool's behavior, output format, and use cases. 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?

Schema coverage is 100% with clear descriptions. The tool description adds minor context (e.g., 'key links' for max_links) but does not significantly enhance understanding beyond the schema.

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

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

Clear verb ('generate') and resource ('llms.txt file for any URL'). Specifies purpose for AI crawlers and distinguishes from sibling tools like scan_competitor_ai_presence by focusing on file generation rather than scanning.

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?

States three concrete use cases (client indexing, own project, competitor audit). No explicit when-not-to-use or alternatives, but the context is sufficiently clear for an AI agent to select appropriately.

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, not destructive. The description adds valuable context: accepted number formats (with/without slashes) and that it returns full metadata including title, inventors, classifications, status, and prosecution events.

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

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

Two sentences: first states action and required input, second states return value. No fluff, front-loaded with key information.

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

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

Given output schema exists and low complexity (2 params, 1 required), the description is sufficient. It covers input format and return details, though could mention idempotency or error behavior for invalid numbers.

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

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

Schema description coverage is 100% and the description does not add additional meaning beyond restating the number format. The description does not elaborate on the _apiKey parameter beyond what is in the schema.

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

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

The description clearly states the tool fetches a single USPTO patent application or grant by application number. It distinguishes itself from siblings like 'search_patents' by being a single-record fetch, and adds specifics on what metadata is returned.

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

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

The description implies use when an application number is available, but does not explicitly compare with alternatives like 'search_patents' or state when not to use it. No guidance on prerequisites or error 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?

Annotations already indicate readOnly and idempotent; description adds specific fields returned and default active-only 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?

Two compact sentences, front-loaded with purpose and return fields, no extraneous 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 list tool, description covers purpose, return fields, and usage context; no output schema needed.

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

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

Schema covers 100% of parameters with description; tool description does not add extra meaning beyond listing return fields.

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 verb 'List', resource 'subscriptions', and scope 'caller's active'. Distinguishes from siblings like subscribe/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?

Provides explicit guidance: use before adding more subscriptions or to find an id to cancel. Could explicitly state not for listing others' subscriptions.

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

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

The description reveals rate limiting (5 per identifier per day), that it's free and doesn't count against tool-call quota, and that the team reads digests daily. These details go beyond the annotations, which only indicate the tool is not read-only, idempotent, or destructive.

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

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

The description is a single paragraph that efficiently conveys purpose, usage, tips, and limitations. Every sentence adds value with no redundancy or fluff.

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

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

The description covers all necessary aspects for a feedback tool: what to submit, how to format, rate limits, and impact on roadmap. No output schema exists, but return values are not needed for this tool.

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

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

Schema coverage is 100%, but the description adds value by elaborating on the enum types (e.g., 'bug = something broke') and providing usage context like not pasting end-user prompts. This enhances understanding beyond the schema.

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

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

The description explicitly states the tool's purpose: to send feedback about bugs, missing features, data gaps, or praise. It clearly distinguishes from sibling tools, which are research/utility tools, by defining specific feedback categories.

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 scenarios for when to use the tool (bug, feature, data_gap, praise) and instructs users to describe issues in terms of Pipeworx tools/packs. However, it does not explicitly state when not to use it or provide 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 read-only, idempotent, non-destructive, and open-world. The description adds transparency about the data source (CF analytics-engine), no PII, and caching duration (5min-1h), which goes beyond what annotations provide.

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

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

Concise, well-structured, with front-loaded purpose. Each sentence earns its place, covering purpose, use cases, and behavioral details without 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?

Despite no output schema, the description fully explains what is returned (top tools, top packs, total call volume) and caching behavior. For a simple read-only tool with one optional parameter, it is 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 covers the single parameter with 100% coverage. The description adds semantic guidance about window choices ('shorter windows surface what's hot right now; longer windows show steady-state demand'), enhancing the schema description.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a window. The verb 'returns' and specific resource list make purpose unambiguous. It distinguishes from siblings like discover_tools by focusing on trending data.

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

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

Explicitly lists three use cases for when to use the tool, providing clear context. Does not explicitly state when not to use or contrast with alternatives, but the listed use cases imply appropriate contexts.

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 extensive context beyond annotations: details internal checks (semantic anchor, partition filter, fill check), explains response structure, and warns when trades should not be executed (realizable_edge_pp ≤ 0). No contradiction with readOnlyHint=true.

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

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

While every sentence adds value, the description is lengthy and could be better structured. It front-loads core purpose but dives into extensive detail, sacrificing conciseness for completeness.

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 comprehensively explains response format (opportunities array with fields, partition_check in event mode). Covers edge cases (placeholder filtering, fill check) and references sibling tools, leaving no critical gaps.

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

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

Schema coverage is 100%, but description adds significant value beyond schema: explains types of arguments (event slugs, topic questions), provides examples, and describes behavior when no args passed. This greatly aids correct invocation.

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

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

Clearly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. Distinguishes three modes (no args, event, topic) and differentiates from siblings by specifying its unique scope.

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

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

Explicitly describes when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. Recommends event mode for specific markets and explains cross-event catches patterns single-event misses. References polymarket_fill_risk for custom sizing.

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 far beyond the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations. It details caching (1h KV-level), three model families with specific algorithms, filtering logic, response structure including diagnostics, and the 24h-move warning. 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?

While the description is thorough, it is verbose and dense, mixing model internals, response structure, and knob explanations. It front-loads the purpose but the extensive details may overwhelm an agent. More concise structuring could improve readability.

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

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

Given the complexity (9 parameters, no output schema, rich behavioral traits), the description is exceptionally complete. It explains the output structure by_segment, fed_candidates, and _diagnostics, along with caching and filter logic. No output schema exists, but the description compensates fully.

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 in the input schema. The description adds significant extra meaning, especially for complex parameters like min_partition_leg_kelly, min_liquidity, max_spread_pp, and slippage_pp, explaining their impact on filtering and edge realization.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the action (scan and return) and resource (Polymarket markets), and distinguishes from siblings like polymarket_arbitrage by its focus on Pipeworx data disagreement.

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 it's built for 'what should I bet on today' and helps agents discover opportunities without paging hundreds of markets. It provides clear use case but does not explicitly mention when not to use it or provide alternatives among sibling tools.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds crucial behavioral details: data bounds (60-day TTL), computation basis (daily closes, not intraday), and note that gaps indicate no scan. These are not in annotations and enhance transparency.

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

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

The description is well-structured with a clear purpose statement, detailed response format, and limits section. It is front-loaded but slightly lengthy; every sentence adds value, though it could be tightened.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) and limits. It covers all necessary context for an agent to understand what the tool returns and its constraints.

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

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

Schema coverage is 100% with descriptions for both parameters (days, window). The description does not add additional meaning beyond what the schema already provides (defaults, ranges, options). Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a specific question ('how long has this edge existed and is it shrinking?'). It distinguishes itself from sibling 'polymarket_edges' by focusing on historical analysis rather than raw edge data.

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

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

The description implies when to use the tool (e.g., comparing fresh vs. old edges) but does not explicitly state when not to use or contrast with alternatives. The response format details, including 'expired' and 'trend', provide context for 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?

Annotations already convey safety (readOnlyHint, idempotentHint, non-destructive). The description adds rich behavioral details: ladder walking, field returns (top_of_book, slippage_pp, etc.), forced_directional_risk naming thin legs. No contradiction.

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

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

The description is long but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET). It is front-loaded with purpose. Slightly verbose but every sentence is informative and earned.

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

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

No output schema, so description must explain returns. It lists all fields for both modes and mentions forced_directional_risk. Lacks explicit response format (e.g., JSON), but completeness for a complex tool is high.

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

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

Schema coverage is 100%, but the description adds critical context: size_usd interpretation differs by mode (spend vs. proceeds; settlement notional for baskets); side auto-defaults based on partition sum. This goes beyond the schema's basic descriptions.

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

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

The description states explicitly: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes single-market and basket modes, and specifies inputs. Sibling tools like polymarket_arbitrage and polymarket_edges are mentioned as triggers, setting it apart.

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

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

The description gives explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why not to skip it, citing thin books and partial fill risks.

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 far beyond annotations (readOnlyHint, openWorldHint, etc.) by detailing response structure (leg-by-leg prices, spread[], top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). It explains when the tool indicates no arbitrage exists (compatibility_warning conditions) and warns about temporal alignment. This level of detail fully discloses 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 long but front-loaded with the main purpose. It is well-structured with sections (modes, response, safety fields). Every sentence adds value, though some technical details (skipped_cross_type/subtype) could be condensed. It earns its length but is not excessively verbose.

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 fully covers response fields: leg-by-leg prices, spread[], compatibility_warning conditions, temporal_alignment, and skipped counters. Given the complexity of cross-venue spreads with two modes and multiple safety checks, the description is comprehensive and leaves no critical gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by listing the 10 topic shortcuts with examples, explaining that explicit parameters override topic-mapped sides, and providing sample values like 'KXFED-26OCT' and 'fed-decision-in-june-825'. This extra context helps agents understand parameter usage beyond the schema definitions.

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

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

The description clearly states the tool computes 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 like polymarket_arbitrage, which likely focus on single-venue arbitrage. The verb 'spread' and resources 'Kalshi' and 'Polymarket' are 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?

The description provides explicit guidance on when to use the tool and when spreads are meaningful. It explains that topic mode auto-fetches events but warns that most pre-mapped topics return compatibility_warning today, indicating it may not always yield tradeable spreads. It also details when explicit mode should be used. Alternatives like polymarket_arbitrage are implied but not directly named, yet 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 already declare readOnlyHint, idempotentHint, destructiveHint. The description adds context beyond that by specifying it retrieves saved values and listing example use cases.

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-loading the core action and then providing usage context. Every word adds value with no redundancy.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers purpose, usage, scope, and related tools completely. It leaves no necessary question unanswered.

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

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

Schema coverage is 100%, and the schema already describes the key parameter's behavior (omit to list all). The tool description reinforces this but adds no new semantic information beyond the schema.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys if no key is provided. It distinguishes itself from siblings like remember and forget.

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

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

It explicitly says when to use it (look up previously stored context) and how it's scoped to an identifier, and mentions pairing with remember and forget for full lifecycle.

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, open-world, and idempotent hints. Description adds useful behavioral detail: the mark_read flag, filtering semantics, and that the same feed is available elsewhere. No contradictions.

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

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

Three sentences, front-loaded with purpose, no filler. Every sentence provides value including parameters, return fields, and usage notes.

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

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

Completely covers a read tool with 5 optional parameters: explains what is returned, how filtering works, and alternative access. No output schema but description compensates adequately.

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. The tool description adds meaning for several parameters: explains type filter, since as ISO timestamp, mark_read effect, and unread_only. Enhances understanding beyond the schema.

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

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

The description clearly states it pulls fired events from the subscription feed and mentions key return fields. It is specific about the resource and action, but does not explicitly differentiate from sibling tools like list_subscriptions.

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

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

Provides context that polls work fine and mentions an alternative endpoint for scripts/dashboards, giving guidance on when to use this tool vs. direct API access.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: it fans out to multiple sources in parallel, explains fallback logic (GDELT preferred, GNews on error), notes USPTO soft-failure due to API sunset, and describes the return structure (grouped changes, total count, citation URIs). 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 front-loaded with user-facing query examples, then succinctly defines the core purpose, lists sources with status, explains parameter usage, and ends with sibling differentiation. Every sentence adds essential information; no wasted words.

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

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

Despite having no output schema, the description explicitly states the return structure ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). It also covers error behavior (USPTO soft-fail) and suggests alternatives (entity_profile). For a tool with 3 required params, 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 coverage is 100% with clear descriptions for 'type', 'since', and 'value'. The description adds extra meaning: restricts 'type' to 'company' only, gives examples for 'since' (ISO date or relative shorthand, recommends '30d' or '1m'), and provides example formats for 'value' (ticker or CIK). This goes 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 opens with multiple concrete example queries ('What's new with X', 'latest on Y', etc.) and then states 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It lists specific data sources (SEC EDGAR, GDELT, GNews, USPTO) and explicitly contrasts with the sibling entity_profile tool. The verb ('change feed') and resource ('company') are precise and actionable.

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

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

The description explicitly instructs when to use the sibling entity_profile instead: 'Use entity_profile instead when you want the static profile... regardless of window.' It also implies usage for dynamic temporal queries. The guidance is clear, but it does not include explicit 'when-not-to-use' scenarios beyond the one sibling comparison.

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

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

The description adds behavioral details beyond annotations: key-value pair scoped by identifier, persistence differences for authenticated vs anonymous users (24 hours), and pairs with recall/forget. It aligns with idempotentHint=true.

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

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

The description is concise (4 sentences) and front-loaded with the core purpose. Every 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?

Given the tool's simplicity (2 required params, no output schema), the description is complete. It explains functionality, pairing with other tools, and behavioral nuances.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description enhances meaning by providing naming examples and context, but adds limited new semantic information beyond the schema.

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

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

The description clearly states the tool's purpose: saving data for reuse across conversations/sessions. It gives concrete examples (resolved ticker, target address, user preference) and distinguishes from siblings by mentioning 'recall' and 'forget'.

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

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

The description explicitly tells when to use the tool: 'when you discover something worth carrying forward... so you don't have to look it up again.' It also explains scoping and persistence differences, providing clear context for its use.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context: internal cascading through multiple endpoints (replacing 2-3 manual lookups), auto-disambiguation for company, and specific return fields per type including citation URIs.

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 examples first, then usage directive, then detailed type-specific returns. It is slightly verbose (e.g., repeating full citation URIs) but every sentence adds substance.

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 explains return values per entity type (ticker, CIK, RxCUI, etc.) and includes citation URIs. It covers inputs, outputs, and internal behavior, making it nearly complete for an entity resolution tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds incremental value by explaining accepted input forms for each type (e.g., company accepts ticker, CIK, or name; drug accepts brand or generic) and auto-disambiguation, but does not fundamentally alter understanding beyond the schema.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers with specific examples (ticker, CIK, RxCUI). It distinguishes itself from siblings by positioning as the first step when an ID is needed, though it doesn't explicitly contrast with other entity-related tools.

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

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

The description explicitly advises 'Use FIRST whenever you have a name but need an ID.' It provides concrete example queries, establishing clear when-to-use context. It lacks explicit when-not-to-use guidance or alternatives, but the directive 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 already indicate readOnly, openWorld, idempotent hints. The description adds that each entity is probed with ai_visibility_check and returns a ranked list with specific fields (score, confidence, signal density). No contradictions with annotations; adds useful behavioral detail.

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

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

The description is three sentences, front-loaded with purpose, no redundant words. It efficiently conveys what the tool does, when to use it, and what it returns.

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

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

Despite no output schema, the description specifies return structure (ranked list with score, confidence, signal density per entity). All four parameters are well-described in schema, and the description provides a complete picture of functionality and outcome.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds the semantic that the first entity in the array is treated as the 'subject' for narrative purposes, which is not in the schema. This extra context meaningfully assists correct usage.

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

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

The description explicitly states it compares AI visibility across multiple entities, uses ai_visibility_check, ranks by score, and surfaces most/least recognized. It clearly distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic) by specifying the composite, competitive audit 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 provides a concrete use case (competitive AI-marketing audits) and an example question, but does not explicitly state when not to use or list alternative tools. However, the context is clear enough for an agent to infer appropriate usage.

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

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

Annotations (readOnly, openWorld, idempotent, non-destructive) are fully supported. The description adds behavioral context: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list if timeout.

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 thorough and front-loaded with the core purpose. It is slightly long but every sentence adds value, no waste. Minor reduction possible but overall efficient.

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

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

Given the composite nature and absence of output schema, the description fully covers return fields (summary block, per-advisory detail, links, alternatives), graceful degradation, and limitations. Complete and self-contained.

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

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

Schema coverage is 100%, both parameters well-described in schema. Description adds no new parameter meaning beyond what schema provides, 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 a composite check for adding an npm package, specifying the two data sources (deps.dev, bundlephobia) and the exact questions it answers. It distinguishes itself from sibling tools by naming its scope and alternatives for other ecosystems.

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

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

Explicit guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and clearly states when not to use ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly').

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds value by disclosing the specific fields returned (title, inventor list, filing date). This complements the annotations well, though rate limits or pagination are not mentioned.

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 sentence that immediately conveys the tool's purpose and return format. Every word earns its place; there is no fluff or redundancy.

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

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

The description explains the return values (title, inventor list, filing date) and the search criterion. Given the presence of a full output schema (not shown but indicated), the description covers the essential behavioral aspects. It does not mention authentication or rate limits, but those are documented in the parameters and annotations.

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

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

The input schema has 100% coverage with descriptions for all three parameters (query, limit, _apiKey). The description does not add additional meaning beyond the schema; it merely restates that the search is by inventor last name. Hence, it meets the baseline but does not compensate further.

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

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

The description clearly states the verb 'Search', the resource 'USPTO patent applications', and the specific criterion 'by inventor last name'. It also specifies the return fields (title, inventor list, filing date), making the purpose unambiguous and distinct from sibling tools like search_patents.

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 does not provide explicit guidance on when to use this tool versus alternatives such as search_patents or get_patent. It simply states what it does, leaving the agent to infer usage context. No exclusions or prerequisites are mentioned.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description adds critical behavioral details: ODP filtering is approximate with best-effort counts/ordering, and the API key fallback behavior. This adds significant value.

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

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

The description is 5-6 sentences, all purposeful. Slightly more structured formatting could improve scanability, but it is concise and front-loaded with the main action.

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

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

Given 8 parameters and an output schema, the description covers usage, filtering behavior, caveats (approximate matching), and return fields. It is complete for an agent to invoke the tool correctly.

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

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

With 100% schema coverage, the description still adds substantial meaning: examples for query (including '*' trick), detailed suffix warnings for applicant, default limit, and date formats. This goes well beyond the schema.

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

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

The description clearly states it 'Search USPTO patent applications and grants' with a specific verb and resource. It distinguishes from sibling tools like search_inventors (focused on inventors) and get_patent (single patent fetch).

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: free-text keywords with optional structured filters. It does not explicitly exclude cases or compare to alternatives, but the context is sufficient for an agent to decide when to use this tool.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. Description adds model details (BGE-base-en with cosine, 500-char windows), truncation at 200K chars, and return fields (offsets, scores). 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?

Description is concise with 4 sentences, front-loading purpose and usage. No fluff, but it is slightly verbose in the technical details (could mention model more briefly). Still, very efficient.

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

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

Despite no output schema, description clearly explains return format (passages with offsets and similarity scores). Covers constraints (200K char truncation), usage scenario, and pairing with sibling tool. Complete for an agent to use correctly.

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

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

Schema covers all 3 parameters with descriptions (100% coverage). Description adds context (e.g., example sources for text, natural-language query examples) but does not substantially extend meaning beyond schema. Baseline 3 is appropriate.

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

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

The description clearly states it performs 'semantic search INSIDE a fetched record', specifies input (text and query) and output (passages with offsets and scores), and distinguishes from sibling ask_pipeworx_grounded by explaining the pairing and when to use each.

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 when the record is too big to cram into the prompt' and mentions alternative ask_pipeworx_grounded for grounding. Also specifies truncation behavior and cap, providing clear when-to-use and when-not-to guidance.

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

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

The description provides rich behavioral context beyond annotations: OAuth requirement, persistence limitations for anonymous users, SMS cap of 10/day, webhook signing details, and that webhook secret is returned once. No contradiction with annotations (readOnlyHint=false, idempotentHint=true consistent with creation).

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

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

The description is dense but efficient, with a clear front-loaded purpose. It could benefit from bullet points for readability, but each sentence independently 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 the tool complexity (3 parameters, nested objects, many types and delivery options), the description covers all necessary aspects: prerequisites, type parameterization, delivery options with constraints, and return value (subscription id). No gaps identified.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value with concrete examples for each type and detailed constraints for delivery channels (e.g., webhook signing, SMS verification). This elevates it above baseline.

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

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

The description clearly states the primary action: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description specifies prerequisites ('Requires a Pipeworx OAuth account'), supported types with examples, and delivery channel constraints (e.g., SMS cap, email verification). It does not explicitly state when not to use, but the context is strong enough for tool selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context by detailing the return format (category-bucketed example questions with exact tool+argument shapes from the live catalog). No contradiction with annotations. Could mention that it is safe and stateless, but annotations cover that.

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

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

The description is information-dense but perhaps slightly verbose with the list of alternative phrasings. However, every sentence contributes value: explains purpose, usage, output format, and parameter details. It is front-loaded with common user queries, making it quickly scannable.

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

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

Given that this is an onboarding tool for a complex agent, the description is complete. It explains what the tool does, when to use it, how to customize it, and what the output contains. No output schema is needed as the return value is explained narratively. Context from siblings shows diverse tools, but this tool's role as first-stop is clear.

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

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

Schema coverage is 100% (one parameter `topic` described). The description adds significant meaning by listing example topic values (finance, pharma, etc.) and explaining that omitting it returns a cross-category spread. This goes beyond the schema's simple string description.

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

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

The description clearly states the tool's purpose: as an onboarding entry point that returns categorized example questions for Pipeworx. It uses specific verbs ('Returns category-bucketed example questions') and distinguishes itself from siblings by positioning itself as the first tool to use when the user doesn't know what Pipeworx can do.

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

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

Explicit instructions are provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. It also explains the optional `topic` parameter to focus on specific areas and what happens when omitted. This gives clear guidance on when to use this tool vs exploring others.

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 that the row is deactivated (not deleted), matching the 'destructiveHint: false' annotation. Adds ownership constraint not captured in annotations, though no further details on rate limits or auth are 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?

Two sentences, no filler, front-loaded with the core action. 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 the single parameter and no output schema, the description fully covers purpose, ownership, and side effects. References related tools ('subscribe', 'recent_alerts') for 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 description coverage is 100%, so baseline is 3. The description adds that the id is from 'subscribe' and is a uuid, but does not significantly enhance meaning beyond the schema.

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

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

Clearly states 'Cancel a subscription by id', specifying the verb and resource. Distinguishes from siblings like 'subscribe' and 'list_subscriptions' by being the inverse operation.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions') and explains the effect (deactivation, not deletion) with a reference to 'recent_alerts', guiding appropriate usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: it returns a detailed verdict with citation and delta, uses specific data sources (SEC EDGAR + XBRL), and explains the return 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 front-loaded with practical trigger phrases, then explains domain, use case, and return format. While somewhat lengthy, each sentence adds value, and the structure is logical.

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

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

Given the single parameter, no output schema, and clear annotations, the description fully explains input, output (verdict, structured form, citation, delta), sources, and domain. It is self-contained and leaves no major gaps.

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

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

The schema has 100% description coverage with a clear parameter description and examples. The tool description adds extra context on the supported claim types (company-financial) and the natural-language focus, enhancing understanding beyond the schema.

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

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

The description starts with clear trigger phrases like 'Is it true that…' and lists synonyms, making the tool's purpose immediately obvious: natural-language claim verification. It specifies the domain (company-financial claims) and distinguishes from sibling tools like 'ask_pipeworx_grounded' or 'bet_research' which have different focuses.

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

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

The description explicitly states when to use the tool ('whenever the agent needs to check whether something a user said is factually correct') and notes the domain limitation. However, it does not explicitly mention alternatives or when not to use, though it implies the scope.

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