Patents

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

The description adds meaningful context beyond the annotations: it specifies the default model, the need for an `_apiKey` for Anthropic, and the cost model (BYO key, pay directly). It also discloses the return structure (per-model score, confidence, signals, raw_response). This enriches the behavioral understanding without contradicting the readOnly/idempotent hints.

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

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

The description is three sentences long, front-loaded with the core purpose, followed by cost/default behavior, and then the return format and use cases. Every sentence contributes unique information, and there is no redundancy or 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?

Given the tool's moderate complexity (4 params, no output schema), the description is complete: it explains the return structure, default model, optional models, API key requirement, and realistic use cases. Combined with the rich annotations and full schema coverage, the agent has sufficient context to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds marginal semantic value beyond the schema—such as clarifying the default model and the direct payment aspect—but mostly reiterates what the parameter descriptions already state. It does not introduce new parameter-level insights 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 uses a specific verb ('Probe') with a clear resource ('one or more LLMs') and outcome ('score visibility (0-100) per model'). It clearly distinguishes itself from sibling tools by focusing on LLM knowledge probing and visibility scoring, which is unique among the listed siblings like compare_entities or scan_competitor_ai_presence.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') that indicate when to use the tool. However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of full 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?

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds significant context beyond annotations: it discloses routing across 5,529 tools, returns structured answers with stable citation URIs, works on every tier, and is a single fast call. No contradictions with annotations.

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

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

The description is front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and is logically structured. However, it is somewhat verbose, with redundant encouragement ('START HERE', 'works on every tier, one fast call') and a long list of examples that partially duplicate schema examples.

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

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

The description fully compensates for the lack of an output schema by explaining what the tool returns (structured answer with citation URIs). It includes scope, limitations, alternatives, and operational characteristics, making the tool's behavior and context 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 schema provides 100% coverage with descriptions for all six parameters, including aliases. The description itself does not add parameter-level detail beyond examples, so it remains at 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 tool's purpose: answering factual questions about real-world data by routing to specialized tools. It explicitly distinguishes itself from web search and sibling tools (ask_pipeworx_grounded, deep_research), and provides concrete examples of use cases.

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

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

The description provides explicit when-to-use guidance: prefer over web search for factual queries, use as the default entry point, and step up to grounded or deep_research only for specific needs. It even lists trigger phrases and example questions, making alternative selection unambiguous.

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 explaining the experimental nature ('experimental edge'), the live activation of candidate routing when under test, the current exact match to stable, and that results are compared to decide merges. It also clarifies that it is a full working router with no fallback, which is key behavioral 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?

Three sentences, front-loaded with 'Beta version of ask_pipeworx', efficiently convey identity, current state, and usage. Every sentence 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?

The description explains the router's purpose, experimental status, and that its response shape matches ask_pipeworx. However, without an output schema, it does not detail the response structure itself, relying on the sibling for that. This is mostly sufficient but not fully 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?

The schema already provides 100% coverage with descriptions for all six parameters (question and its aliases). The description only says 'same arguments' without adding deeper meaning, so it does not elevate beyond the schema 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 that this is a beta version of ask_pipeworx, a universal router that handles the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable sibling by enabling candidate routing improvements, making its purpose and differentiation explicit.

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 is provided: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that currently no candidate is active and it matches ask_pipeworx exactly, giving clear when-to-use context. The alternative (stable router) is implied by referencing ask_pipeworx.

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 establish read-only, idempotent, non-destructive behavior. The description adds substantial behavioral context: it extracts using ONLY tool results, returns a structured object with evidence/refusal_reason, lists specific refusal reasons, and notes the extra LLM call. This goes far beyond the annotations without contradiction.

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

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

The description is dense yet well-structured: purpose, process, return format, usage guidance, cost comparison. Every sentence contributes essential decision-making information. It's appropriately sized for the tool's complexity and front-loads the main purpose.

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

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

Despite having no output schema, the description fully specifies the return structure and refusal cases. It covers the tool's operation, its relationship to siblings, and actionable usage guidance. For a simple single-parameter tool, this description leaves no critical gap in the agent's understanding.

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

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

Schema coverage is 100% with a clear description of the question parameter and all aliases. The description does not add parameter-specific detail, but since the schema thoroughly documents the input, the baseline of 3 applies. The description's mention of 'fills arguments' implies the question is natural language but adds no additional semantic value beyond the schema.

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

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

The description opens with a precise, differentiated purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It contrasts with the sibling ask_pipeworx by specifying grounded extraction, return format, and refusal behavior. This clearly distinguishes it from other tools in the list.

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: 'Use whenever an answer will be quoted, cited, or acted on...' and when not to: 'prefer ask_pipeworx for casual lookups.' Also provides the extra cost trade-off, giving clear decision criteria versus the sibling ask_pipeworx.

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

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

Beyond the annotations (read-only, idempotent), the description reveals extensive behavioral traits: resolver contract with match confidence levels, safety short-circuit on low-confidence matches, handling of closed markets, news fallback retry fields, wide-spread tradeability warnings, and cancellation-rule risk parsing. This gives the agent a thorough understanding of runtime behavior and edge 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 quite long and dense, with numerous examples and detailed sections. It is organized with capitalized labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES) which helps structure, but it could be trimmed without losing essential guidance. It is front-loaded with the core purpose and usage, but the overall length prevents a higher score.

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

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

With no output schema, the description compensates by thoroughly explaining response shapes (result.market, result.analysis, result.evidence), resolver match confidence, parent_event extractor, news fields, safety mechanisms, and resolution-rule risks. It covers edge cases and provides actionable guidance for the agent, making the tool's behavior predictable and 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 schema already provides 100% coverage with descriptive text for all three parameters (market, depth, include_raw). The description adds examples and context (e.g., input formats and fan-out depth implications) but does not significantly enhance parameter understanding beyond what the schema already offers. Baseline 3 is appropriate.

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

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

The description clearly states the tool's specific purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It distinguishes from siblings by focusing exclusively on Polymarket bets and describing the parallel fan-out to category-specific data packs. Examples of input formats further clarify its 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?

The description explicitly provides usage guidance with 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. This gives clear context for when to apply the tool. However, it does not explicitly name alternative tools or define when-not-to-use scenarios, so it falls short of a 5.

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

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

Annotations already declare read-only, idempotent, and non-destructive hints. The description adds rich behavioral context: data sources (SEC EDGAR/XBRL, FAERS, FDA), off-calendar fiscal year handling, result sorting by primary metric, and citation URIs. This goes well beyond the annotations and provides the agent with important operational expectations.

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

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

The description is longer than average but every sentence carries useful information: examples, data sources, fiscal year handling, sorting, and performance benefit. It is front-loaded with user-facing query patterns and avoids fluff, though it could be tightened slightly without losing 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?

For a tool with two types, multiple data sources, no output schema, and complex behavior, the description is remarkably complete. It accounts for data provenance, edge cases (off-calendar fiscal years), sorting, response format (paired data + citations), and scalability advantage. A user or agent would know exactly 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%, so baseline is 3. The description adds substantial meaning: type='company' pulls specific financial metrics, type='drug' pulls adverse-event/trial counts, and values are tickers/CIKs vs drug names. It also explains that results are sorted by primary metric, which is not evident from 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 uses a specific verb+resource: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It includes concrete query examples and explicitly distinguishes itself from sequential single-pack lookups, making the tool's purpose unmistakable and differentiating it from siblings like entity_profile.

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

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

The description gives clear usage context: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and lists example query patterns. It implies when not to use (single entity lookups) but doesn't explicitly name a specific alternative tool such as entity_profile, so it falls just short of fully explicit when/when-not/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?

The description goes far beyond the annotations by detailing the findings packet, gaps array, contradictions scan, hop field, citation_uri, time expectations, and semantic excerpting. It also discloses that it never invents answers and that citations are fetchable, providing rich behavioral context not present in the readOnlyHint/openWorldHint/idempotentHint 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 densely packed with essential details for a complex tool. It is front-loaded with the account requirement and what the tool does, then flows through usage, behavior, and output structure. While every sentence earns its place, some redundancy (e.g., repeating 'gaps[]') slightly reduces conciseness.

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

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

With no output schema, the description fully explains the return format (findings packet, evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop field). It covers execution time, prerequisites (account), and alternatives, making it complete for a complex research tool with multiple parameters 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%, giving baseline 3. The description adds meaning beyond the schema by explaining the behavioral implications of each depth value (e.g., 'standard' adds gap recovery, 'thorough' adds iterative hop) and that the question can be broad/multi-part, reinforcing the schema's descriptions.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call.' It distinguishes itself from siblings like ask_pipeworx by emphasizing it is NOT open-web search and returns a findings packet.

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 is provided: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also notes the account requirement and the alternative to use ask_pipeworx when not signed in, covering when/when-not and alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds behavioral value by explaining the return format (top-N tools with full schemas, ready to call) and the efficiency benefit (no second schema lookup), which goes beyond annotations.

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

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

The description is four sentences, front-loaded with the core purpose, then usage, return value, and placement guidance. The domain list is extensive but purposeful, and no sentences are wasted.

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 meta-nature, rich schema, and annotations, the description covers purpose, when to use, return value, and workflow placement. It does not explain the ranking algorithm, but that is not required for tool invocation. With no output schema, the description's explanation of return contents is helpful.

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 all six parameters documented including aliases. The description's reference to 'describing the data or task' mirrors the query parameter's schema description but adds no new meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb 'Find tools' and clearly identifies the resource (tools) and mechanism (describing data/task). It distinguishes from sibling tools by listing covered domains and framing itself as a discovery meta-tool, not a domain-specific search tool.

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

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

It explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set.' This is clear context, though it does not name specific alternative tools to avoid.

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 behavior. The description adds meaningful behavioral context: it fans out across multiple sources, includes a specific failure mode ('USPTO PatentsView API sunset May 2025 — soft-fails until reactivated'), and describes a fallback mechanism (GDELT→GNews). These go beyond what annotations provide.

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

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

The description is a single dense paragraph that is front-loaded with example queries and then provides return details. While every sentence carries useful information, it could benefit from bullet points or more deliberate structure for easier scanning. Still, it is efficient and not redundant.

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

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

With no output schema, the description thoroughly explains return values: recent filings (up to 5 with URIs), fundamentals (LATEST 10-K fields), patents (with source note), news (with fallback), and LEI. It also covers input constraints and error-prone cases (names not supported). This is complete for a complex multi-source 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?

The input schema covers both parameters with detailed descriptions, including the ticker/CIK format and the 'names not supported' note. The description essentially restates the same parameter information, so it adds no new semantics 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: creating a full cross-source profile of a US public company. It uses specific verbs like 'profile', 'research', and 'brief me on', and lists exact return fields (CIK, filings, fundamentals, patents, news, LEI), distinguishing it from single-source lookups and sibling tools.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', providing clear when-to-use guidance. It also states that names are not supported and directs users to 'resolve_entity first', which is an explicit alternative.

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

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

Annotations already disclose destructiveHint=true and idempotentHint=true, covering the core safety profile. The description adds 'clear sensitive data' as a use-case but not extra behavioral traits such as missing-key handling or permission requirements. Minimal added value 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 each serve a distinct purpose: state the action, give usage criteria, and relate to sibling tools. No redundancy and the key action is front-loaded.

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

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

For a simple one-parameter deletion tool with no output schema, the description covers purpose, usage, and sibling relationships. Annotations provide the safety profile, so no major gaps remain 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?

Schema description coverage is 100% with 'Memory key to delete' for the single parameter. The description's phrase 'by key' merely restates the schema property without adding new meaning. Baseline 3 is appropriate when the schema carries the full burden.

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

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

The description uses a specific verb ('Delete') and resource ('memory by key'), clearly distinguishing this tool from siblings like 'remember' and 'recall'. The pairing statement reinforces its unique role in the memory lifecycle.

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

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

Explicit when-to-use conditions are provided ('when context is stale, the task is done, or you want to clear sensitive data'). Pairing with remember and recall gives context but does not explicitly state alternatives like 'use recall to retrieve'. Clear guidance but no exclusions.

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

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

Annotations already declare read-only and idempotent behavior. The description adds that it fetches, extracts, and emits markdown, and clarifies the output is a single text blob. This is useful process transparency beyond the annotations without contradiction.

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

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

The description is four concise sentences, front-loaded with the core purpose, followed by process, output format, and use cases. Every sentence adds value and there is no wasted wording.

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 only two parameters and no output schema, the description covers purpose, process, output format, and use cases. It explains the return value ('single text blob') and the standard format, making it complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100% for both parameters, so the schema fully documents url and max_links. The description does not add new parameter-level semantics beyond what the schema already provides, warranting the baseline score of 3.

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

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

The description clearly states the verb 'Generate' and the specific resource 'llms.txt file for any URL'. It explains the output and distinct use cases, distinguishing it from siblings like ai_visibility_check or scan_competitor_ai_presence by its concrete deliverable.

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

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

The description provides explicit use cases (client indexing, own project, competitor audit) which give clear context for when to use the tool. However, it does not explicitly state when not to use it or mention direct alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value by specifying that it returns full metadata (title, inventors, classifications, status, prosecution events) and that it fetches a single record, providing scope beyond static annotations.

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

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

The description consists of two sentences, front-loads the primary purpose, and includes concrete examples of the identifier format. Every word is useful, 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 tool is simple with two params (one required), an output schema exists, and annotations cover safety and idempotency. The description adequately conveys the single-record scope and return contents. It could mention more about when not to use it, but the overall information is sufficient for effective selection and 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 description coverage is 100%, so both parameters (number and _apiKey) are already documented in the schema. The description repeats the example format for the number parameter but does not add new semantic information beyond what the schema provides, warranting the baseline score of 3.

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

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

The description clearly states 'Fetch a single USPTO patent application/grant by application number,' which specifies a verb, resource, and identifier format. It distinguishes itself from siblings like search_patents (searching) and get_patent_assignments (assignments) by focusing on single-record retrieval.

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 by specifying it fetches a single patent by application number, which is clear context. However, it does not explicitly mention alternatives (e.g., 'use search_patents for query-based lookup') or exclusions, so it falls short of a 5.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description discloses a crucial behavioral caveat: recorded assignments are 'notice of a submitted instrument—not a legal opinion on present title, validity, scope, liens, or chain-of-title completeness.' It also names the specific endpoint source, adding transparency about data provenance and limitations.

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: the first states purpose and return fields, the second adds a necessary interpretive caveat. Every sentence earns its place with no repetition or fluff, and it is front-loaded with the most important 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 the simple one-required-parameter tool, the presence of a full output schema, and complete annotations, the description covers all necessary information: what it does, what it returns, and critical limitations. No gaps remain 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 coverage is 100% with clear descriptions for _apiKey and application_number. The description does not add parameter-specific meanings beyond the schema, but it does reinforce the 'one patent application' context. This meets the baseline for well-documented 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 'Retrieve USPTO-recorded assignment/conveyance history for one patent application', which is a specific verb, resource, and scope. It lists the exact data returned (assignors, assignees, dates, conveyance text, reel/frame), clearly distinguishing it from siblings like get_patent or 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 clearly states it is for retrieving assignment history for a single patent application, implying the appropriate context. However, it does not explicitly mention alternative tools or when not to use it, missing the opportunity to contrast with sibling tools like validate_claim or search_patents.

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 read-only, non-destructive, idempotent behavior. The description adds valuable behavioral details: it enumerates the exact fields returned (id, type, params, created_at, last_fired_at, fire_count) and clarifies the caller-scoped nature, which is extra context beyond annotations.

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

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

The description is two sentences: the first states purpose and output, the second provides usage guidance. Every sentence contributes value with no redundancy or 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 read-only list tool with one optional parameter and no output schema, the description covers the return fields, scope, and practical use cases. It could explicitly mention the include_inactive parameter in prose, but the schema already documents it, so the overall completeness 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% and the sole parameter include_inactive is well-described in the schema. The description implies active-only default but does not add substantive meaning beyond the schema, so 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 (List), the resource (the caller's active subscriptions), and the scope (caller's). It distinguishes from sibling tools like subscribe and unsubscribe by focusing on reading subscriptions rather than modifying them.

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

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

The description provides explicit use cases: 'review what you're monitoring before adding more or to find an id to cancel.' This gives clear context for when to use the tool, though it does not mention explicit exclusions or alternative tools.

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

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

Annotations are all false (no hints), so the description carries the full burden. It discloses meaningful behavioral traits: the claim_token return and re-query mechanism, rate limiting (5/day), zero cost (doesn't count against quota), and human reading cadence (daily digests). This goes well beyond the minimal safety 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?

Front-loaded with purpose and immediate usage guidance. Each sentence adds either a usage condition, a constraint, or a procedural detail. Despite covering many nuances (exclusions, token flow, rate limits, cost), it remains compact and skimmable with no redundant phrasing.

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 moderate complexity: four params (one enum, one nested object), no output schema, and nuanced usage policies. The description covers all essential aspects: when to file, exclusions, what to write, account-optional behavior, claim token flow, rate limits, and cost. No critical 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%, so parameters are already documented. The description adds extra value by telling users to describe issues in terms of Pipeworx tools/packs and not to paste end-user prompts, which goes beyond the schema. It also clarifies the claim_token's dual purpose as a status reader. This lifts it above the baseline for fully-schema-covered tools.

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 'Tell the Pipeworx team something is broken, missing, or needs to exist,' a clear specific verb+resource. It clearly distinguishes from siblings like ask_pipeworx or discover_tools by being exclusively about feedback on the tools, not using them.

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?

Gives explicit when-to-use scenarios (bug, feature/data_gap, praise) and an explicit when-not-to-use exclusion for tools from other MCP servers. Names the alternative action ('file it with that server instead'), making the guidance actionable and unambiguous.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint=false), the description discloses caching behavior (5min-1h), the absence of PII, and the aggregation source (CF analytics-engine). This gives the agent a clear picture of staleness and data scope without contradicting 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 compact and front-loaded, with the core functionality in the first sentence. The 'Useful for' bullets and cache/privacy notes each add distinct value; no sentence is wasted.

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 one optional, fully documented parameter and strong annotations, the description adequately covers what the tool returns (top tools, packs, count) and the aggregate format. The lack of an output schema is mitigated by the explicit '(pack, tool, count)' detail, making this complete for a low-complexity 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?

The only parameter, window, is fully documented in the schema with enum values and semantics ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The description merely restates the available windows, adding no new meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states a specific verb ('Returns') and resource: top tools, top packs, and call volume over selectable windows. It differentiates from sibling tools like discover_tools by framing this as an aggregation of what other AI agents are calling on Pipeworx, and by listing concrete use cases.

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

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

It provides explicit use cases (discovering hot data sources, confirming canonical tool, aligning use case) and guidance on window selection. It stops short of naming sibling alternatives or stating when not to use it, so not a full 5.

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

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

Even with readOnlyHint and idempotentHint annotations, the description adds substantial behavioral detail: the 3pp deviation threshold, Jaccard similarity ≥0.30, placeholder filtering with >20% fraction returning null, and the fill-check logic explaining that realizable_edge_pp ≤ 0 means 'do not trade it.' This goes far beyond what annotations provide and discloses important edge-case 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 logically organized with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the primary purpose. The length is justified by the tool's complexity, but it is denser than strictly necessary and could be trimmed slightly without loss of meaning.

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 covers return values ('opportunities[]', 'partition_check{...}', 'skipped_low_similarity') and edge cases ('null arb signal', 'realizable_edge_pp ≤ 0'). It also explains thresholds and failure modes, making it complete for a complex tool with multiple modes.

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

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

Schema coverage is 100% with descriptions for both 'event' and 'topic', but the tool description significantly enriches them. It gives concrete examples (e.g., 'fed-decision-may-2026' vs 'Fed rate decision'), explains what accepting a URL means, and clarifies the behaviors triggered by each parameter. This exceeds 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 opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly identifies the tool's scope (Polymarket arbitrage) and differentiates from siblings by naming modes, thresholds, and the fill-check behavior. The mention of 'For custom sizing use polymarket_fill_risk' further distinguishes it from a sibling tool.

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

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

The description provides explicit when-to-use guidance: 'Call with NO args for a `trending_scan`... pass `event`... or `topic`...' It recommends 'event (recommended for a specific market)' and explains when topic mode is appropriate versus single-event. It also directs users to polymarket_fill_risk for custom sizing, showing clear decision boundaries between 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 annotations already mark the tool as readOnly, idempotent, and non-destructive, but the description adds substantial behavioral context beyond those hints: 1-hour KV-level caching, response diagnostics explaining why segments may be empty, fed_candidates excluded from ranking with rationale, the 24h-move warning, and edge_pp_net being net of slippage. This is extensive 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 dense and front-loaded, with the first two sentences covering purpose and use case. Every sentence carries useful information, and the length is justified by the tool's complexity (three model families, nine knobs, response details). However, the lack of paragraph breaks and reliance on ALL-CAPS labels makes it harder to scan; structure could be improved.

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 exists, the description compensates thoroughly by detailing the response top-level structure (by_segment, fed_candidates, _diagnostics), model family mechanics, caching behavior, and filter semantics. It is sufficiently complete for an agent to invoke and interpret the tool's outputs.

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?

Input schema already covers 100% of parameters with descriptions, but this description elevates the semantics by grouping min_liquidity/max_spread_pp as 'TRADEABLE-EDGE KNOBS,' explaining that partition_overround returns kelly_fraction_half=0 at parent level so min_kelly does not apply, and clarifying how slippage_pp interacts with edge and ranking. This meaningfully improves parameter understanding.

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

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

The first sentence clearly states the tool's action and scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further distinguishes the tool's purpose with 'Built for "what should I bet on today"' and outlines three distinct response segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), making it easy to differentiate from sibling tools.

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

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

The description provides a clear use case: agents discover opportunities 'without paging hundreds of markets,' and it explains how to tailor results via tradeable-edge knobs like min_liquidity and max_spread_pp. However, it does not explicitly name alternative sibling tools or state when NOT to use this tool, so it falls just short of full exclusionary 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?

Even though annotations already declare read-only, idempotent, and non-destructive behavior, the description goes far beyond by explaining the response structure (tracked/expired/snapshot_dates), the meaning of trend categories, how decay is computed on absolute values, and the 60-day snapshot TTL. It also discloses that snapshots are written only on cache-miss, so gaps represent days with no scan. This is rich behavioral transparency that annotations alone do not 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?

Although longer than average, the description is well-structured with labeled sections (Args, RESPONSE, LIMITS) and each sentence adds essential detail. It is front-loaded with the core purpose and then expands logically into parameters, response, and limitations. No redundancy or filler is present.

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

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

With no output schema, the description fully specifies the return structure (tracked[], expired[], snapshot_dates[]) and explains each field's semantics, including trend categories and lifespan_days. It also covers data-availability caveats like TTL and cache-miss behavior. The tool is straightforward in complexity (2 optional params) and the description leaves no important gap.

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 already covers 100% of parameters with descriptions, but the tool description adds more: days has a default of 14 and max of 30, window has a default of '1wk' and explains that it refers to 'window family.' The description also defines the meaning of decay_pp_per_day and notes that snapshots are per-window. This significantly exceeds the schema's parameter documentation.

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

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

The description states exactly what the tool does: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from the sibling polymarket_edges by focusing on historical persistence rather than current edges. The contrast between fresh and old edges clarifies the tool's unique value.

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: when you need to distinguish a fresh edge from a stale one, or track decay over time. It also provides context about snapshot gaps and TTL limits. However, it does not explicitly name alternative tools or state 'use this instead of polymarket_edges when you need history,' so the guidance is clear but not exhaustive.

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

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

Annotations already declare readOnly/OpenWorld/idempotent/non-destructive, but the description adds substantial behavioral detail: it walks the order-book ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and a verdict. It also discloses mode-specific risks like thin_legs[], forced_directional_risk, and the requirement that exactly one of market/event be provided. No annotation contradiction exists.

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 it is dense with necessary operational detail and clearly organized by SINGLE-MARKET and BASKET sections. The purpose is front-loaded, every sentence contributes meaning, and the length is justified by the tool's complexity and the absence of an output schema.

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

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

With no output schema, the description fully carries the burden of explaining returns—it enumerates the complete output fields for both modes and provides prerequisites, defaults, financial interpretation, and failure modes. This makes the description functionally complete for a complex 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?

Although the schema has 100% description coverage for its four parameters, the description goes far beyond it. It clarifies side defaults and auto behavior, distinguishes size_usd as 'max spend' vs 'target proceeds' in single-market mode and 'settlement notional' where each share pays $1 in basket mode, and notes the clamp range (10–1,000,000).

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 a specific verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this risk-checker from sibling trading tools by explicitly naming the workflows it precedes ('polymarket_arbitrage' and 'polymarket_edges'), and it details two distinct modes (single-market and basket).

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 explains why (theoretical overround on thin books is not capturable, partial basket fills convert arb into unhedged directional risk) and clearly distinguishes single-market vs basket usage via parameter requirements.

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

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

Annotations already declare read-only, idempotent, non-destructive, and open-world behavior. The description goes far beyond this by exposing compatibility_warning conditions, temporal_alignment semantics, and skipped_cross_type/subtype counters, including honest caveats like 'most pre-mapped topics return compatibility_warning today.' This is exemplary behavioral disclosure.

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 densely packed with necessary information: purpose, modes, response format, edge cases, and limitations. It is front-loaded with the core definition and uses structured lists (e.g., TWO MODES, SAFETY FIELDS). Some sentences are overloaded with parenthetical asides, but overall every sentence contributes 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?

With no output schema, the description carries the full burden of explaining return values and behavioral nuances. It thoroughly covers leg-by-leg prices, top_spreads_pp, compatibility_warning triggers, temporal alignment, and skipped-category counters. Given the tool's complexity and the absence of structured output metadata, this description is remarkably 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 input schema already provides 100% coverage for the three parameters. The description adds meaningful semantic context by explaining the two modes, the relationship between topic and the explicit override parameters (e.g., 'Overrides the topic-mapped Kalshi side'), and how they interact. This exceeds the schema baseline but doesn't dramatically expand each parameter's meaning beyond precedence and 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 opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly specifying the tool's function and distinguishing it from siblings like polymarket_arbitrage (which likely focuses on single-venue arbitrage). It also details two operation modes, making the tool's scope 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?

It explicitly explains both modes and when to use them: topic shortcuts for pre-mapped events and explicit ticker/slug for custom pairings. It also provides strong when-not guidance via compatibility_warning and temporal_alignment, warning that pre-mapped ≠ tradeable. However, it does not directly name alternative tools or explicitly say 'use this instead of X,' so it falls short of a 5.

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

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

With annotations already declaring readOnly, idempotent, and non-destructive behavior, the description adds valuable context about scoping (anonymous IP, BYO key hash, or account ID) and data provenance (saved via remember). This goes beyond what annotations state and aids correct usage.

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 at three sentences, opens with the primary action, and each sentence adds distinct value: function, use case, scoping, and companion tools. No filler 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?

For a simple tool with one optional parameter, no output schema, and strong annotations, the description fully covers what an agent needs: what it does, when to use it, scope, and pairing with related tools. It is complete enough for correct selection and 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?

The input schema already fully describes the single 'key' parameter including the omit-to-list behavior, so schema coverage is 100%. The description confirms this and adds contextual meaning (e.g., scoping), but does not provide substantial new parameter-level detail 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 uses a specific verb (retrieve/list) and names the resource (previously saved values/keys), and clearly distinguishes from sibling tools by naming remember and forget. It also gives concrete examples of stored context, making the purpose unmistakable.

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

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

The description provides clear context for when to use the tool (looking up previously saved context to avoid re-deriving it) and explicitly names companion tools (remember, forget). It lacks an explicit 'when not to use' statement, but the guidance is sufficiently clear within the tool's purpose.

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

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

The description discloses that setting mark_read:true flags returned events as read, which is a state-changing side effect. However, the annotations declare readOnlyHint:true, implying no state modification. This is a direct contradiction, so the description fails to align with the annotation despite being transparent about the actual 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 five sentences, front-loaded with the core purpose. Each sentence adds useful detail (return fields, filtering, mark_read side-effect, alternative endpoint). The HTTP endpoint sentence is helpful but slightly beyond the core tool behavior, keeping it from a 5.

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

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

Given the tool has no output schema, the description adequately explains the return fields, filtering options, and the mark_read side effect. It also mentions an alternative access method. The only significant gap is the contradiction with the readOnlyHint, but that is a transparency issue rather than descriptive 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?

The input schema has 100% description coverage for all five parameters. The description adds an example type ("sec_8k") and clarifies the mark_read behavior, but most parameter meanings are already in the schema. The added value is marginal, so 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 tool's function: "Pull fired events from your subscription feed" and specifies what it returns (recent alerts with source, citation_uri, and raw event payload). This specific verb+resource+scope distinguishes it from siblings like recent_changes and 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?

The description provides practical usage context: "Polls work fine" indicates suitability for repeated polling, and "the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards" offers an alternative for non-agent use. It does not explicitly exclude sibling tools but gives enough context for 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?

Beyond the annotations (readOnly, idempotent, openWorld), the description reveals multi-source fan-out behavior, fallback logic (GDELT→GNews when rate-limited or 5xx), and the USPTO API sunset soft-fail condition. It also describes the return structure (changes[], total_changes, pipeworx:// URIs) without an output schema, carrying the full burden of behavioral disclosure. 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 appropriately sized and front-loaded with example queries, then efficiently covers sources, fallback behavior, parameters, return format, and an alternative tool—all in a compact, well-structured paragraph. Every sentence provides actionable information, with no redundancy or 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?

Given the tool's multi-source orchestration (SEC, GDELT/GNews, USPTO) and the absence of an output schema, the description adequately explains the data sources, error handling (soft-fail, fallback), return structure (changes[], total_changes, citation URIs), and the distinction from entity_profile. It is complete for an agent to invoke and interpret the result 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 already provides 100% coverage with detailed descriptions for all three parameters (type, since, value), including allowed formats and examples. The description adds minimal new semantic detail, mostly reinforcing the same information (e.g., since accepts ISO or relative) and adding a usage tip. This meets the baseline of 3 for high schema coverage without adding substantial meaning beyond it.

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

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

The description clearly identifies the tool as a change feed for companies, explicitly listing the query patterns it answers ("What's new with X", "latest on Y") and the sources it fans out to (SEC EDGAR, GDELT/GNews, USPTO). It distinguishes itself from sibling entity_profile by contrasting dynamic changes vs static profile, making the tool's 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 explicit guidance on when to use this tool vs entity_profile ("Use entity_profile instead when you want the static profile..."), and gives concrete usage recommendations for the `since` parameter ("Use '30d' or '1m' for typical monitoring"). It also explains fallback behavior (GDELT preferred, GNews on rate limits/5xx) and the USPTO soft-fail, helping the agent choose correctly.

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

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

The description adds valuable behavioral context beyond the annotations: memory is scoped by agent identifier, authenticated users get persistent memory, anonymous sessions get 24-hour retention. It does not contradict the idempotent or non-destructive hints, and the added details are meaningful.

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

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

The description is concise and front-loaded with the purpose. Every sentence adds useful information: what it does, when to use it, persistence behavior, and companion 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 two-parameter tool with no output schema, the description covers purpose, usage, persistence details, and related tools. It fully equips an agent to decide when and how to invoke it.

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

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

Schema coverage is 100% with descriptive parameter names and examples (key and value). The description only says 'key-value pair' and adds no extra meaning beyond what the schema already provides, so a baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for later reuse, using the specific verb 'Save' with the resource being data/memory. It also distinguishes itself from siblings by explicitly mentioning 'Pair with recall to retrieve later, forget to delete.'

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 gives concrete when-to-use guidance ('when you discover something worth carrying forward') and names alternatives (recall, forget). However, it does not explicitly state when not to use the tool, so it stops short of a 5.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description goes beyond by disclosing graceful degradation (LEI/FIGI enrichment falls back to EDGAR identifiers), cascading internal lookups, source labeling, and explicit reporting of unresolved identifiers. This adds significant behavioral context beyond the structured annotations.

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

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

The description is dense but mostly earns its length—it packs usage examples, tool purpose, supported types, output details, and failure behavior into one paragraph. It is front-loaded with high-value examples, though it could be slightly tightened by trimming redundant phrasing. Slight redundancy in listing trigger phrases, but acceptable.

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

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

With no output schema, the description must carry the return-value documentation, and it does: it explicitly lists all identifiers returned for company and drug, notes source attribution, and explains what happens when enrichment endpoints are unavailable. It also covers input validation (accepted values) and error behavior (unresolved identifiers), making the tool fully understandable without an output schema.

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

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

Schema coverage is 100% but the description provides richer semantics: it explains what each 'type' resolves to (company returns CIK+ticker+name+LEI+FIGI; drug returns RxCUI+ingredient+brand), what input formats are accepted, and how the output is structured (unresolved fields are included not omitted). This goes far 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 opens with concrete example queries and clearly states the tool's function: resolving user-spoken names to canonical/official identifiers. It distinguishes itself from siblings like entity_profile and compare_entities by specifying the exact output identifiers (CIK, ticker, LEI, FIGI, RxCUI) and supported entity types.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing an unambiguous trigger condition. It also lists the types of queries it handles (ticker, CIK, company name for company; brand/generic for drug) and notes that it replaces 2-3 manual lookups, giving clear guidance on when to select 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond annotations: it probes each entity via another tool, ranks by score, and surfaces most/least recognized entities. It also states the return includes a ranked list with score, confidence, and signal density. However, it does not disclose rate limits or latency implications of probing multiple models, but the added context is solid given 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 three sentences long and each sentence earns its place: first states the core action and output, second explains the mechanism and example use case, third lists the return contents. It is front-loaded with the key verb and resource, and avoids unnecessary detail or repetition of schema content.

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

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

The tool is moderately complex with 4 parameters (1 required) and no output schema, but the description explains the return format (ranked list with score, confidence, signal density) and the processing flow (probe each entity, rank, surface most/least recognized). It also provides a concrete use case, making the tool's behavior and output understandable enough for an agent to select and invoke it correctly. The annotations and rich schema descriptions cover the remaining details.

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

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

Schema coverage is 100% for all four parameters, and the descriptions in the schema are already detailed (e.g., supported models, required API key condition, shared context, entity ordering). The description adds semantic value by clarifying that the first entity is the 'subject' and the rest are competitors, and by explaining the comparison/ranking behavior. Since the schema already covers parameter meaning well, the description's incremental value is modest but meaningful.

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

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

The description uses a specific verb ('Compare AI visibility'), names the resource (multiple entities side-by-side), and explicitly distinguishes from sibling tools by naming the probe method (ai_visibility_check) and competitive-audit use case. The example query ('does Claude know about us as well as our competitors?') further clarifies the tool's unique 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?

It clearly states when to use this tool (competitive AI-marketing audits), gives a concrete example of the use case, and implicitly contrasts with ai_visibility_check (single entity) by saying 'across multiple entities' and 'side-by-side.' The description also indicates the first entity is treated as the subject, which guides correct invocation.

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 valuable behavioral context: partial failures degrade gracefully, bundlephobia's first measurement may take 5-30s, and sources_failed will list timeouts. This goes beyond the safety hints to describe latency and failure modes.

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

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

The description is longer than the ideal (4 sentences), but each sentence conveys necessary information: purpose, usage triggers, return payload, ecosystem limitations, and failure behavior. It's dense but well-structured with a clear opening verb and logical flow, though it could be slightly trimmed.

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

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

For a composite tool with no output schema, the description thoroughly describes the return values (summary block fields, per-advisory detail, links, alternative versions), the ecosystem scope, and grace-degradation behavior. It leaves no major gaps for an agent to understand what it gets and when to use it.

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

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly (package name, version with default-to-latest). The description adds no new parameter semantics beyond the schema; it does mention the returned 'is_latest' field which indirectly relates to the version parameter, but this is marginal. Baseline of 3 is appropriate.

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

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

The description clearly states it's a composite check for 'should I add this npm package to my project' in one call, with specific data sources (deps.dev, bundlephobia) and what it measures (license, advisories, bundle size, etc.). This distinguishes it from sibling research tools like deep_research or validate_claim, which are broader or different in focus.

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 whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Also provides an exclusion/alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This tells the agent when to use this tool and when to use a different path.

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, and destructiveHint=false, covering safety and side-effect behavior. The description adds a small amount of context about the return fields, but nothing about rate limits, auth requirements, or other behavioral traits. 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 two short sentences that front-load the action and include only essential information. No filler or redundant content.

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

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

The tool is a simple search with strong annotations, fully described schema, and an output schema. The description covers the core purpose and returns, making it complete for an agent to select and invoke correctly. No missing contextual information.

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 fully describes all three parameters (100% coverage), including the USPTO cap on limit and the meaning of query. The description does not add any additional parameter-level semantics beyond what the schema already 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 the action ('Search USPTO patent applications'), the specific search field ('by inventor last name'), and the return value ('title, inventor list, and filing date'). This distinguishes it from sibling tools like search_patents, which likely search by other criteria.

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 usage is implied by the specific search criterion (inventor last name), but the description does not explicitly mention when to use this tool over alternatives like search_patents. No exclusions or 'when-not-to-use' guidance 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?

Beyond the readOnly/idempotent annotations, the description discloses critical behaviors: USPTO hard-caps results at 25 records per search, common synonyms map to canonical filters, corporate suffix mismatches yield zero results plus a `warning` field, and 'query' searches the whole record while 'title' searches only the invention title. These are non-obvious and highly actionable.

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

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

The description is moderately long but every sentence serves a purpose: it front-loads the core action, then systematically covers query syntax, filters, synonyms, result cap, return fields, and data source. Could be tightened slightly (e.g., inline examples), but there is 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?

With 11 parameters and an output schema present, the description still covers all critical aspects: query semantics, each filter's behavior, result cap, return fields, synonym mappings, and the USPTO data source. It gives enough contextual information for an agent to use filters effectively without encountering zero-result pitfalls.

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

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

Schema coverage is 100%, and the description still adds substantial value: it explains AND logic for `query`, quoting, '*' wildcard, exact suffix pitfalls for `applicant`, accepted synonyms for multiple params, and the meaning of `warning`. This goes far 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 opens with a specific verb and resource: 'Search USPTO patent applications and grants.' It clearly distinguishes itself from siblings like get_patent (which retrieves specific documents) and search_inventors (which focuses on inventors) by covering broad free-text and structured filtering across 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?

Provides explicit usage context: how to use `query` (AND semantics, phrase quotes, '*' wildcard), when to prefer `applicant`/date filters over `limit` (due to 25-record cap), and exact corporate suffix requirements. It doesn't explicitly name alternative tools (e.g., get_patent for specific documents), but its guidance on query formulation and result cap 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?

The description discloses rich behavior beyond annotations: returns character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char overlapping windows, and truncates inputs over 200K chars with a flag. This is exactly the kind of contextual detail that helps an agent understand side effects and limitations. 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 a single paragraph but front-loaded with purpose. Every sentence adds value: when to use, what it returns, how it works, and the size limit. It is slightly dense but appropriate for the tool's complexity, meriting a 4 rather than 5.

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

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

With no output schema, the description fully explains return values (top-N passages with offsets and scores). It covers truncation, embedding model, chunking strategy, and pairing with a sibling tool. The description is complete for the agent to decide when to invoke and what to expect.

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

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

Schema coverage is 100%, so baseline is 3. The description adds valuable context: 'text' is the already-pulled record, 'query' is natural-language, and 'limit' controls passage count. It also clarifies practical usage (e.g., 'pass the text you already pulled') that goes beyond raw schema descriptions, earning a 4.

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

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

The description opens with a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes this from siblings by naming ask_pipeworx_grounded and explaining the complementary role. The purpose is unmistakable and differentiates from other search/query 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 states when to use: 'Use when the record is too big to cram into the prompt.' Also names the alternative workflow with ask_pipeworx_grounded ('fetch with the gateway, ground over the relevant passages instead of the whole document'). Provides clear context and exclusions (e.g., size cap).

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 only provide hints (readOnlyHint=false, idempotentHint=true, etc.), but the description adds rich behavioral context: OAuth requirement, anonymous/BYO cannot persist, SMS verification and 10/day cap, always-on feed, webhook auto-disable after 10 failures, and one-time signing secret. These details go well beyond the structured annotations and set clear expectations for the caller.

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

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

The description is dense but well-structured, front-loading the core purpose and then covering requirements, types, and delivery channels in a logical order. It repeats some schema details but every sentence contributes useful context, making it appropriately sized for a multi-option subscription tool.

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

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

Given the tool's complexity (3 parameters, nested objects, multiple subscription types, multiple delivery channels) and lack of output schema, the description is comprehensive. It covers purpose, return value, authentication, type-specific examples, all delivery options, and relevant constraints, fully equipping the agent to use the tool correctly.

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

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

Schema description coverage is 100% and the input schema already details each parameter, including type-specific filters (sec_8k, polymarket_edge, fred_series, etc.). The description reiterates examples (e.g., items:['5.02']) but adds little new meaning beyond what the schema provides, so a 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 opens with 'Create a proactive monitoring subscription to a live-data event stream', which uses a specific verb (Create) and clearly identifies the resource (monitoring subscription). It also states the return value ('Returns the new subscription id'), distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides clear prerequisites ('Requires a Pipeworx OAuth account') and explains the always-on feed with explicit retrieval alternatives ('pull via recent_alerts or GET registry.pipeworx.io/alerts.json'). It does not explicitly name sibling tools for exclusion, but the context strongly implies when to use subscribe versus when to read alerts.

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

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

The annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds behavioral context beyond annotations: it explains the output structure ('category-bucketed example questions'), the source ('drawn from the live catalog of thousands of tools'), and the purpose of onboarding. 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 longer than a single sentence but dense and highly informative. It front-loads the example user queries, then explains the output and usage. Every sentence contributes value, though the list of categories could be seen as somewhat verbose. Still, it is efficiently structured for an agent.

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

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

With no output schema, the description must explain return values, and it does: it lists the category buckets and notes each suggestion includes the exact tool and argument shape. It also covers invocation modes (no args vs. topic) and the intended use case. For a simple meta-tool with one optional parameter, 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% for the single `topic` parameter, so baseline is 3. The description adds value by giving concrete examples ('finance', 'pharma', 'betting') and clarifying the effect of omitting the parameter ('full spread' vs. 'focus'). This reinforces and extends the schema description without redundancy.

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: it is 'the onboarding entry point for an agent that just connected' and 'returns category-bucketed example questions' with the exact tool and argument shape. It uses a specific verb ('returns') and a resource (example questions) that distinguishes it from siblings like ask_pipeworx or discover_tools by framing it as the first step to learn what to ask.

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 is provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. This tells the agent when to use it and directly names alternatives (ask_pipeworx, entity_profile, compare_entities). It also explains parameter usage: 'Call with no arguments for the full spread, or pass topic to focus'.

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

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

Beyond the annotations (idempotentHint, destructiveHint:false), the description reveals that cancellation is not a physical delete but a deactivation, and that historical events remain accessible. The ownership enforcement is also disclosed, adding meaningful behavioral context. 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 two sentences, front-loaded with the action, and every sentence contributes value: the first states the core operation, the second adds ownership and deactivation detail. No wasted words.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers all essential aspects: what it does, ownership restriction, the non-destructive behavior, and how historical data is preserved. It references recent_alerts for continuity, making it 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?

The schema already fully describes the 'id' parameter (subscription id returned by subscribe). The description repeats 'by id' but does not add new semantic meaning beyond the schema's high coverage (100%). Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Cancel') and resource ('a subscription by id'), clearly distinguishing this from sibling tools like subscribe (create) and list_subscriptions (list). It is immediately obvious 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 explains when to use the tool (to cancel a subscription by id) and adds an important constraint: ownership is enforced. It also mentions an alternative path (recent_alerts) for historical data, implying the tool does not remove history. It does not explicitly name subscribe/list_subscriptions as alternatives, but the context is sufficient.

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

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

Annotations declare readOnly/openWorld/idempotent, and the description adds critical behavior: describes verdict variants and warns that 'could_not_verify' is not evidence but a failure indicator. It also explains the dual pipeline (SEC EDGAR vs grounded) and return format with citation, going well beyond the annotations.

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

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

The description is dense and front-loaded with trigger phrases, which aids agent matching. It includes some redundancy (e.g., restating fact-check purpose) and a long example list, but each section carries useful information, so it earns its length despite minor inefficiencies.

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 verdicts, citation, reasoning, and the semantics of 'could_not_verify' and 'unsupported.' It covers usage, behavior, and error handling, leaving no major gaps 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?

Input schema covers both parameters with detailed descriptions (claim examples and tolerance_pct behavior). The description adds little beyond that—only reinforcing tolerance behavior with 'exact percent-delta math.' With 100% schema coverage, 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?

Description opens with natural-language triggers and states 'natural-language claim verification against authoritative sources,' which is a specific verb+resource. It clearly distinguishes the tool from sibling tools by focusing on fact-checking claims (verify/confirm/refute) rather than generic queries or 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?

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' and delineates two claim paths (company-financial vs any other). However, it doesn't explicitly name alternative sibling tools for exclusion, so it falls short of a full when-not-to-use guidance.

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