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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes key traits: it uses Pipeworx to pick tools and fill arguments, and returns results. However, it lacks details on limitations (e.g., rate limits, data source availability, error handling) or performance aspects. The description doesn't contradict annotations, but for a tool with no annotations, it provides only moderate behavioral insight.

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 appropriately sized and front-loaded: the first sentence states the core purpose, followed by explanatory details and examples. Every sentence earns its place by clarifying functionality or providing concrete use cases, with no redundant or vague language. It efficiently conveys the tool's value in a compact format.

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 (natural language querying with backend tool selection) and no output schema, the description is mostly complete. It explains the process and gives examples, but lacks details on output format, error responses, or constraints like query length. With no annotations, it could benefit from more behavioral context, but it adequately covers the core functionality for an agent to use it correctly.

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

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

The input schema has 100% description coverage, with the 'question' parameter well-documented as 'Your question or request in natural language.' The description adds value by emphasizing 'plain English' and providing examples (e.g., 'Look up adverse events for ozempic'), which clarifies the expected format and scope beyond the schema's basic definition. With only one parameter, this extra context is sufficient for a high score.

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

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

The description clearly states the tool's purpose: 'Ask a question in plain English and get an answer from the best available data source.' It specifies the verb ('ask'), resource ('answer'), and mechanism ('Pipeworx picks the right tool'), distinguishing it from sibling tools like search_patents or get_patent that require specific parameters. The examples further clarify its broad, natural-language query capability.

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

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

The description provides clear context on when to use this tool: for natural language questions where you don't need to browse tools or learn schemas. It implies usage by stating 'No need to browse tools or learn schemas' and gives examples like 'What is the US trade deficit with China?' However, it doesn't explicitly state when not to use it or name alternatives among siblings, such as using search_patents for structured patent queries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral details such as the extra LLM call cost, response structure with refusal reasons, and the extraction process using only tool results, enhancing transparency without contradiction.

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

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

The description is somewhat lengthy but front-loaded with the main purpose. Every sentence adds value, though it could be slightly more concise without losing clarity.

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

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

Given tool complexity (6 params, 1 required, high schema coverage) and no output schema, the description explains the output format, refusal reasons, and trade-off with sibling tool, making it fully complete for effective use.

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

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

Schema description coverage is 100% with aliases documented. The tool description does not add significant meaning beyond the schema, but baseline 3 is appropriate as schema already handles parameter semantics.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' with specific verb 'ask' and resource 'Pipeworx,' distinguishing it from sibling 'ask_pipeworx' by emphasizing grounded extraction and explicit refusal reasons.

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

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

Explicitly advises using when answers will be quoted, cited, or acted on and must not invent facts, and suggests preferring 'ask_pipeworx' for casual lookups, providing clear context and alternatives.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds extensive behavioral details: low-confidence resolution short-circuit, closed market handling, wide-spread market flagging, resolver contract with match confidence, parent event extraction, and news fallback fields. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It front-loads the main purpose and usage. Some examples could be shortened without losing clarity, but overall every section earns its place.

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

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

Given the tool's complexity and lack of output schema, the description is remarkably thorough. It covers response shapes, resolver contract, parent event extraction, news fields with fallback, safety mechanisms, and closed market behavior. This provides a complete mental model for correct invocation and interpretation of 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%. The description adds meaningful context for each parameter: for 'market' it explains acceptable formats (slug, URL, text); for 'depth' it clarifies quick vs thorough behavior; for 'include_raw' it explains default summary vs full payload size. This adds value beyond the schema enums and 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 researches a Polymarket bet by pulling Pipeworx data. It specifies inputs (slug, URL, question text) and outputs (evidence packet, comparison). It distinguishes from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on a single bet research with evidence gathering.

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

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

The description explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). However, it does not explicitly mention when to avoid this tool or point to alternatives among siblings, though the fan-out examples and classifier list provide some 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?

No annotations are provided, so the description carries full responsibility. It mentions return type (paired data + URIs) but does not disclose whether the tool is read-only or if there are side effects. The description implies a safe query operation, but explicit safety traits are missing.

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

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

Two sentences with no fluff. The first sentence states the core function, and the second adds details on types and output. Every sentence earns its place.

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

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

For a tool with 2 parameters and no output schema, the description covers the purpose, input constraints, and output format. It also mentions the efficiency gain. No gaps are apparent.

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

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

Schema coverage is 100% with descriptive parameter entries. The description adds value by explaining what each type returns (e.g., revenue for company, trials for drug), which goes beyond the schema's simple enum. This helps the agent understand the purpose of each parameter.

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

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

The description clearly states it compares 2-5 entities side by side, specifies two types (company and drug) with distinct data fields, and highlights efficiency gains. This is specific and distinct from sibling tools like search_patents or resolve_entity.

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

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

The description explains what the tool does and when to use it (comparing entities). It does not explicitly state when not to use it, but the context and sibling tools make alternatives clear. A slight improvement would be to mention that it is not suitable for single-entity queries.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: it performs a search based on natural language queries, returns relevant tools with metadata, and has a specific use case (large catalogs). However, it doesn't mention potential limitations like rate limits, authentication needs, or error conditions, leaving some behavioral aspects unspecified.

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 perfectly concise and front-loaded. The first sentence states the core functionality, the second explains the return value, and the third provides crucial usage guidance. Every sentence earns its place with no wasted words, making it highly efficient and well-structured.

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

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

Given the tool's moderate complexity (search functionality with 2 parameters) and the absence of both annotations and output schema, the description does a good job of explaining what the tool does and when to use it. However, it doesn't describe the return format (beyond 'names and descriptions') or potential search limitations, leaving some contextual gaps that could be important for an agent.

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

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

The input schema has 100% description coverage, providing full documentation for both parameters. The description doesn't add any parameter-specific information beyond what's in the schema (e.g., it doesn't explain query formatting nuances or limit implications). This meets the baseline of 3 since the schema already does the heavy lifting, but no extra value is added.

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 with specific verbs ('search', 'returns') and resources ('Pipeworx tool catalog', 'most relevant tools with names and descriptions'). It distinguishes from siblings by focusing on tool discovery rather than patent/inventor searches, making the purpose unambiguous and well-defined.

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: 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task.' This gives clear context about usage scenarios (large tool catalogs) and positioning (first step in tool selection), with no misleading or missing guidance.

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

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

Annotations already cover readOnly, openWorld, idempotent, destructive. Description adds details on data sources, return fields, patent soft-fail, and news fallback, enriching the annotation context.

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

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

Well-structured with examples first, but slightly verbose with repeated 'names not supported' and some technical details that could be streamlined.

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

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

No output schema, but description fully explains return fields and sources. Covers all key behaviors for a complex multi-source tool, ensuring an agent knows what to expect.

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

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

Schema coverage is 100% and description reinforces each parameter: type limited to 'company', value as ticker or CIK, explicitly stating names not supported. Adds meaning beyond schema.

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

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

Description opens with concrete examples and states 'full cross-source profile of a US public company in ONE parallel call.' Clearly distinguishes from siblings like resolve_entity.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack [...] lookups when the user asks for a holistic view' and directs to use resolve_entity first if only a name is provided.

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

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

No annotations are provided, so the description carries full burden. While 'Delete' implies a destructive mutation, the description doesn't disclose whether deletion is permanent, reversible, requires specific permissions, or has side effects. It mentions the target ('stored memory') but lacks behavioral details like confirmation prompts or error conditions.

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, efficient sentence with zero wasted words. It's front-loaded with the core action and resource, making it immediately understandable. Every word earns its place in conveying the essential function.

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

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

For a destructive tool with no annotations and no output schema, the description is incomplete. It doesn't explain what 'delete' entails (e.g., permanent removal, soft delete), what happens on success/failure, or how this interacts with sibling tools. Given the mutation nature and lack of structured data, more behavioral context is 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 description coverage is 100% for the single parameter 'key', which is documented as 'Memory key to delete'. The description adds minimal value beyond this, only implying the parameter's purpose without additional context like key format or examples. With high schema coverage, the baseline 3 is appropriate.

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

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

The description clearly states the action ('Delete') and the resource ('a stored memory by key'), providing a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'recall' or 'remember', which likely interact with the same memory system.

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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, when deletion is appropriate, or what happens to deleted memories. With siblings like 'recall' and 'remember', there's no indication of when deletion should be chosen over retrieval or storage.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It indicates this is a read operation ('Get') and specifies the scope ('US patent'), but doesn't mention potential limitations like rate limits, authentication requirements, error conditions, or whether the data is real-time. The description adds basic context but lacks comprehensive behavioral traits.

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

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

The description is efficiently structured in two sentences: the first states the purpose and parameter, the second lists the returned fields. Every element serves a purpose with zero wasted words, making it appropriately sized and front-loaded with the core functionality.

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 low complexity (single parameter, no output schema, no annotations), the description provides adequate context for basic usage. It covers what the tool does, what parameter it needs, and what data it returns. However, without an output schema, it could benefit from more detail about the return structure beyond the field names listed.

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

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

Schema description coverage is 100% with the single parameter 'number' well-documented in the schema. The description adds minimal value beyond the schema by mentioning 'patent number' and providing an example format in parentheses, but doesn't significantly enhance parameter understanding beyond what the structured schema already provides.

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

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

The description clearly states the verb ('Get full details') and resource ('specific US patent'), specifying it's for a single patent identified by number. It distinguishes from sibling tools search_inventors and search_patents by focusing on retrieval of complete information for a specific patent rather than searching across multiple patents or inventors.

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

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

The description implies usage context by specifying 'by patent number' and listing the returned fields, suggesting this tool should be used when you have a specific patent number and need comprehensive details. However, it doesn't explicitly state when NOT to use it or name alternatives like the sibling search tools, missing full explicit guidance.

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

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

Annotations already 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?

Discloses rate limiting (5 per day) and privacy guideline (no verbatim prompts). No annotations provided, so description carries behavioral disclosure burden. Could mention if feedback is stored or anonymous, but sufficient for a feedback tool.

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

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

Three sentences: purpose, usage guidance, and constraints. No wasted words, front-loaded with key information.

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

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

No output schema needed (fire-and-forget feedback). Schema fully documents parameters. Description covers all necessary usage context. Complete for a simple feedback tool.

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

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

Schema description coverage is 100% with detailed descriptions for type (enum), context (optional object), and message (max 2000 chars). Description adds no significant meaning beyond schema, but baseline is 3 due to high coverage.

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

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

Description clearly states 'Send feedback to the Pipeworx team' and enumerates use cases: bug reports, feature requests, missing data, or praise. This distinguishes it from sibling tools which are data retrieval or interaction 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?

Provides explicit guidance on when to use (for feedback), what to avoid (do not include user prompt verbatim), and rate limits (5 per day per identifier). Alternatives are clear from sibling tool names.

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

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

Annotations already 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?

The description goes beyond annotations by detailing the exact behavioral traits: it walks child markets, performs partition checks, uses Jaccard similarity (≥0.30), filters placeholder slugs, and returns structured opportunities. It also explains what happens with rejected pairs and partitions. Annotations already confirm read-only and non-destructive, so the description adds substantial context.

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

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

The description is appropriately sized for a complex tool; it is front-loaded with the requirement and main purpose. However, it includes some details that could be streamlined (e.g., the full response structure), but overall every sentence adds value. It is structured with sections for each mode and filters, making it 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 the tool's complexity and the absence of an output schema, the description adequately covers the return values (opportunities and partition_check). It explains all aspects of usage, filters, and behavior. However, it does not mention error scenarios (e.g., what if both parameters are provided) or handle edge cases, which would make it 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?

The description adds significant meaning beyond the input schema: it explains that 'event' accepts full URLs, distinguishes between modes, and provides examples. The schema only gives a brief description, while the tool description gives the usage logic and behavior for each parameter. With 100% schema coverage, the description elevates the semantic understanding.

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

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

The description clearly states the verb 'Find' and the specific resource 'arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks'. It distinguishes itself from siblings by detailing the method and two modes (event/topic), which are unique among sibling tools like polymarket_edges. The purpose is explicit 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 states the requirement to provide either 'event' or 'topic' and recommends which to use based on the goal (single-event vs cross-event). It provides clear context for each mode and mentions filters (Jaccard similarity, placeholder fraction). However, it does not compare itself to sibling tools like polymarket_edges, so usage relative to alternatives is implied but not directly stated.

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?

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the dual functionality (retrieve by key or list all) and mentions persistence across sessions, which is valuable context. However, it doesn't address potential limitations like memory size constraints, retrieval failures, or authentication requirements.

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 efficiently structured in two sentences: the first explains the core functionality, and the second provides usage context. Every word earns its place with no redundancy or unnecessary elaboration.

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

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

For a tool with one optional parameter, 100% schema coverage, and no output schema, the description provides adequate context about what the tool does and when to use it. It could be more complete by hinting at the return format (e.g., structured data vs. raw text) or error conditions, but it covers the essentials well.

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

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

Schema description coverage is 100%, so the schema already documents the optional 'key' parameter. The description adds meaningful context by explaining the semantic effect of omitting the key ('list all stored memories') and relating it to retrieving saved context, which goes beyond the schema's technical specification.

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 with specific verbs ('retrieve', 'list') and resources ('previously stored memory', 'all stored memories'). It distinguishes this from sibling tools like 'remember' (store) and 'forget' (delete) by focusing on retrieval operations.

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

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

The description provides explicit guidance on when to use this tool: 'to retrieve context you saved earlier in the session or in previous sessions.' It also specifies when to omit the key parameter to list all memories, offering clear operational context without needing to reference alternatives directly.

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

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

Annotations already 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: it fans out to multiple sources with fallback logic (GDELT→GNews), mentions rate limits and soft-fails (USPTO), and describes the return structure. 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 relatively long but efficiently packed with information. It front-loads with example queries and immediately states the core function. Every sentence adds value, though minor redundancy exists ('change feed ... in ONE parallel call' could be merged).

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 explains the return format (changes[] grouped by source, total_changes count, pipeworx:// URIs). It covers fallback behavior, soft-fails, and parameter nuances. For a complex tool with 3 required parameters, this 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 descriptions cover 100% of parameters. The description adds meaning beyond the schema: for `since`, it provides examples and a recommended default; for `value`, it explains ticker vs. CIK; for `type`, it clarifies that only 'company' is supported. This enriches the agent's understanding.

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

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

The description uses specific verbs ('change feed', 'fans out') and clearly identifies the resource ('company in the last N days'). It lists example queries ('What's new with X') and explicitly distinguishes from sibling tool entity_profile ('Use entity_profile instead when you want the static profile').

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

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

The description provides clear context for when to use this tool ('latest on Y', 'updates on Acme') and when not to use it ('use entity_profile instead ... regardless of window'). It offers guidance on the `since` parameter ('Use "30d" or "1m" for typical monitoring'). However, it does not exhaustively list all non-use cases.

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?

With no annotations provided, the description carries the full burden and adds valuable behavioral context: it discloses persistence differences (authenticated users get persistent memory, anonymous sessions last 24 hours) and the tool's role in session management. It doesn't cover rate limits or error handling, but provides key operational details beyond basic functionality.

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 the core purpose in the first sentence, followed by usage context and behavioral details. Every sentence earns its place with no wasted words, making it efficient and well-structured for quick comprehension.

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 moderate complexity (storage with session-based persistence), no annotations, and no output schema, the description is mostly complete: it covers purpose, usage, and key behavioral traits. However, it lacks details on return values or error cases, which would be helpful for full completeness.

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

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description does not add meaning beyond what the schema provides (e.g., no additional syntax or format details). Baseline 3 is appropriate as the schema does the heavy lifting.

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 specific action ('Store a key-value pair') and resource ('in your session memory'), distinguishing it from sibling tools like 'forget' (remove) and 'recall' (retrieve). It explicitly mentions what can be stored ('intermediate findings, user preferences, or context across tool calls'), making the purpose unambiguous.

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

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

The description provides clear context on when to use this tool ('to save intermediate findings, user preferences, or context across tool calls'), but does not explicitly mention when not to use it or name alternatives (e.g., 'recall' for retrieval). It implies usage for persistence across sessions but lacks explicit exclusions.

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

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

No annotations are provided, so the description should fully disclose behavior. It describes the read operation (resolve, return IDs) and output details, but lacks explicit statements about safety (e.g., no mutation, idempotency) or error conditions.

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, then details, then benefit. Every sentence earns its place 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?

The tool has no output schema, but the description compensates by enumerating returned fields (ticker, CIK, name, URIs) and noting efficiency gains. It could mention failure modes or case sensitivity, but is largely complete for a simple lookup.

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 providing concrete examples ('AAPL', '0000320193', 'Apple') and clarifying the value parameter's accepted formats beyond the schema's generic description.

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

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

The description clearly states the tool resolves an entity to canonical IDs, specifying the supported type (company) and acceptable inputs (ticker, CIK, name). It distinguishes from sibling tools like search_patents by focusing on entity resolution.

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

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

The description indicates it replaces 2–3 lookup calls, providing strong usage context. It could be more explicit about when not to use it, but the version note (v1: type=company) and examples guide appropriate use.

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

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

Annotations already 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?

No annotations are provided, so the description carries the full burden. It mentions the return data (inventor name, location, patent numbers) but does not disclose critical behavioral traits such as whether this is a read-only operation, potential rate limits, authentication requirements, error handling, or pagination details beyond the 'per_page' parameter in the schema.

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 with zero waste: the first sentence states the purpose and scope, and the second specifies the return values. It is appropriately sized, front-loaded with key information, and efficiently structured.

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

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

Given no annotations and no output schema, the description provides basic purpose and return data, but lacks details on behavioral aspects like safety, performance, or error handling. For a search tool with two parameters and 100% schema coverage, it is adequate but has clear gaps in transparency.

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

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

Schema description coverage is 100%, so the schema already documents both parameters ('query' and 'per_page') with their types and descriptions. The description adds no additional parameter semantics beyond what the schema provides, such as format examples or constraints, meeting the baseline for high schema coverage.

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

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

The description clearly states the specific action ('Search'), resource ('US patent inventors'), and filtering criterion ('by last name'), distinguishing it from sibling tools like 'get_patent' (likely retrieves a single patent) and 'search_patents' (searches patents rather than inventors). It provides a complete picture of what the tool does.

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

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

The description implies usage for searching inventors by last name, but does not explicitly state when to use this tool versus alternatives like 'search_patents' or provide any exclusions or prerequisites. The context is clear but lacks explicit guidance on 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?

No annotations are provided, so the description carries the full burden. It mentions the search scope (US patents, abstracts) and return fields, but lacks behavioral details such as pagination behavior (implied by 'per_page' parameter), rate limits, authentication needs, or error handling. The description adds some context but is insufficient for a mutation-free tool with no annotation coverage.

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

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

The description is two concise sentences with zero waste: the first states the action and scope, the second lists return fields. It is front-loaded and appropriately sized for a simple search tool, with every sentence earning its place.

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

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

Given the tool's low complexity (search with 2 parameters), 100% schema coverage, and no output schema, the description is minimally adequate. It covers purpose and return fields but lacks behavioral context (e.g., pagination, limits) and explicit usage guidelines. Without annotations, it should do more to compensate, but it meets the baseline for a simple tool.

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

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

Schema description coverage is 100%, so the schema already documents both parameters ('query' and 'per_page') with descriptions. The description adds no additional parameter semantics beyond what the schema provides, such as search syntax or result ordering. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the tool searches US patents by keyword, matching against abstracts, and returns specific fields (patent number, title, date, inventors, assignee). It distinguishes from 'get_patent' (likely a detail lookup) and 'search_inventors' (inventor-focused search), though not explicitly. The purpose is specific but lacks explicit sibling differentiation.

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

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

The description implies usage for keyword-based patent searches against abstracts, but does not explicitly state when to use this tool versus alternatives like 'search_inventors' or 'get_patent'. No exclusions or prerequisites are mentioned, leaving the agent to infer context from the tool name and description.

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?

Description adds significant behavioral context beyond annotations: returns verdict types (confirmed, refuted, etc.), structured form, actual value with citation, and percent delta. Also notes efficiency gain (replaces 4-6 calls). No contradiction with annotations (readOnlyHint, etc.).

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

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

Description is well-structured: opens with usage patterns, followed by when-to-use, scope, outputs, and benefits. Every sentence adds value without redundancy.

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

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

Given the tool's single parameter and no output schema, description adequately covers input expectations, output structure (verdict, structured value, citation, delta), scope limitations, and efficiency advantages.

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 parameter description in schema is clear. Description provides examples of valid claims ('Apple's FY2024 revenue was $400 billion') that enhance understanding beyond schema alone.

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

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

Description clearly defines the tool as natural-language claim verification with example triggers ('Is it true that...', 'fact check'), specific verb+resource ('verify the claim'), and distinguishes from siblings by its unique function of claim verification against authoritative sources.

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 whenever the agent needs to check whether something a user said is factually correct' and clarifies scope (company-financial claims via SEC EDGAR + XBRL). Lacks explicit exclusions or 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.