Osv

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 behavioral details: default model is free, Anthropic requires BYO key and direct payment, and the return structure. It does not mention rate limits or data usage, but annotations cover safety adequately.

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

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

The description is concise (about 80 words) and well-structured. The first sentence states the main action, the second provides usage details and return format. No redundant 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 no output schema, the description explains the return structure (per-model score, confidence, signals, raw_response plus combined view). It covers model selection and entity disambiguation with context. However, it doesn't clarify how to interpret the score or signals, leaving some gaps.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds extra context: default model specifics, entity examples, and the role of context. While the schema already defines parameters, the description enriches understanding of their use.

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 probes LLMs about an entity and scores visibility (0-100). The verb 'probe' and resource 'LLMs' are specific, and it distinguishes itself from sibling tools like ask_pipeworx or compare_entities by focusing on AI visibility scoring.

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

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

The description provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the default free model vs. Anthropic with a key. However, it does not explicitly state when NOT to use this tool or contrast with 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds valuable behavioral context: it routes to many tools, fills arguments, returns stable `pipeworx://` citation URIs, works on every tier, and is a 'fast call'. This goes beyond what annotations provide and helps the agent set 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 long but densely packed with useful information, front-loaded with 'PREFER OVER WEB SEARCH'. Each sentence earns its place—scope, examples, alternatives, and a clear START HERE directive. It's not as tight as a two-sentence description, but given the tool's broad scope, the length is justified and well-structured.

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

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

With no output schema, the description still tells the agent what to expect (structured answer with citation URIs). It covers the tool's scope, use cases, alternatives, and even handles breaking-news edge cases. For a complex routing tool, this is a complete and self-contained description.

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

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

Schema coverage is 100% (all six params are documented as aliases for 'question'), so the baseline is 3. The description adds semantic value by giving example queries and trigger phrases ('what is', 'look up', etc.), which help an agent formulate the 'question' parameter. However, it doesn't elaborate on the alias mechanics beyond what the schema already provides, so I don't give a 5.

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

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

The description clearly states the tool routes questions to 5,558 tools across 1,461 sources and returns structured answers with citation URIs. It explicitly differentiates from siblings like ask_pipeworx_grounded and deep_research, making its purpose and position 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 explicit when-to-use guidance (default entry point for factual questions), including many concrete examples and trigger phrases. It also names specific alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions) and even mentions web search as a fallback, giving clear decision criteria.

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

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

The description goes beyond the provided annotations by explaining the experimental nature, the current inactive-candidate state, and that it is a fully working router with no fallback. It discloses exactly how behavior may differ (candidate routing improvements) and reassures that it currently matches ask_pipeworx, giving the agent realistic 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 four sentences and each sentence carries useful information: beta status, identical nature, current candidate status, usage instruction, and fallback clarification. It is slightly longer than strictly necessary, but there is no fluff or repetition. Front-loading 'Beta version of ask_pipeworx' immediately establishes the context.

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

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

For a tool with no output schema and a simple single-question parameter, the description covers the beta identity, experimental routing, current state, and usage. It references the stable ask_pipeworx for response shape and arguments, which is sufficient given the sibling context. It could include an example but is otherwise complete for an agent to invoke it correctly.

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

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

The input schema already provides 100% coverage with descriptions for all six parameters (question and its five aliases). The description only mentions 'same arguments' without adding new meaning, so it does not compensate beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies this as the beta version of ask_pipeworx and describes it as an identical universal router with the same 5,558 tools, arguments, and response shape. This distinguishes it from the stable sibling while assuming some familiarity with ask_pipeworx. It could more explicitly state that it answers natural-language questions by routing, but 'universal router' plus the 'ask' prefix conveys the core function.

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

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

The description explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing', providing a clear condition for when to choose this tool. It also explains that results are compared against the stable router, implying the alternative use of ask_pipeworx for stability. This is strong, actionable guidance.

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

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

The description discloses behavioral traits beyond the annotations: it returns a structured refusal (with specific refusal_reason values) when data doesn't directly answer, and it costs one extra LLM call. This adds meaningful context about failure modes and resource usage 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 front-loaded with the core purpose, then efficiently covers mechanism, return format, usage guidance, and cost trade-off. Each sentence adds specific value without redundancy; it is detailed but appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (routing across 5,558 tools, extraction, refusal reasons) and the absence of an output schema, the description fully compensates by specifying the success and refusal return shapes. It also covers safety, cost, and sibling differentiation, 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% because all six parameters are aliases for 'question' and are documented in the schema. The description adds no new parameter-specific semantics beyond reinforcing that a natural language question is required, so the baseline of 3 applies.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode' that routes like ask_pipeworx, fetches data, and extracts answers strictly from tool results. It distinguishes itself from sibling ask_pipeworx by emphasizing high-stakes reads and the extra LLM call cost, making the purpose specific and non-overlapping.

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 when an answer will be quoted, cited, or acted on and facts must not be invented, with concrete examples (financial, legal, medical, public statements). It also explicitly advises preferring ask_pipeworx for casual lookups, giving clear when/when-not and alternative directions.

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

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

The description adds substantial behavioral context beyond annotations: it explains fan-out behavior, response shapes, resolver contract, parent event extraction, news fallback, safety short-circuits, closed market handling, wide spread warnings, and resolution-rule risk. All of this is useful for an AI agent to understand tool behavior.

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

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

The description is extremely long (multiple paragraphs) and lacks clear structuring (e.g., bullet points, sections). While it contains valuable information, it is not concise and may overwhelm an AI agent. It would benefit from breaking into summarized sections.

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

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

Given the complexity and absence of output schema, the description thoroughly covers all relevant aspects: resolution confidence, parent events, news fallback, safety, closed markets, wide spreads, and cancellation rules. It provides a complete picture of what the tool returns and how to interpret 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%, so baseline is 3. The description adds meaningful context: it explains that 'market' accepts slug, URL, or question text; 'depth' choices are 'quick' (2-3 sources) vs 'thorough' (full fan-out); 'include_raw' controls response size. This enhances understanding beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question text) and gives usage examples. This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage, which focus on different aspects of betting.

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 recommends usage: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides extensive guidance on interpreting results, including resolution confidence, parent events, and safety mechanisms. However, it does not directly contrast with alternative sibling tools or state when not 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?

Description adds meaningful context beyond annotations: details data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), explains handling of off-calendar fiscal years, and mentions returns of paired data with citation URIs. No contradiction with readOnly/ idempotent annotations.

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

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

Description is slightly long but well-structured with front-loaded key phrases and examples. Every sentence adds value, though some repetition of 'comparison' could be tightened. Still effective.

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

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

Given no output schema, description adequately covers return format (paired data + citation URIs). Provides sufficient context for a tool that handles two entity types with different data sources and constraints (2-5 items).

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

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

Schema coverage is 100% with both parameters described. Description enriches by explaining the meaning of 'type' values (company vs drug) and providing concrete examples for 'values' (tickers/CIKs for company, drug names for drug).

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

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

Description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs, differentiating it from single-entity tools like entity_profile. Includes specific use-case examples such as 'compare X and Y' and 'rank these companies'.

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

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

Explicitly advises to prefer this tool over sequential single-pack lookups when comparing entities, and provides example queries. However, it does not specify when not to use it or mention alternatives beyond the general preference statement.

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 hints, but the description adds substantial context: account/auth requirements, paid 'thorough' tier, explicit gap[] handling with 'never invented', citations only when resolvable, contradictions[] in standard/thorough, semantic excerpting of large records, and expected latency (15-90s). No contradiction with annotations 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 a single dense paragraph, but most sentences provide necessary operational detail for a highly complex tool. Some redundancy exists (e.g., depth behavior is repeated from the schema) and the structure could be improved with bullet points, but the critical account warning is front-loaded. It earns a 4, not lower, because almost every sentence adds value.

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

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

With no output schema, the description fully compensates by enumerating the findings packet contents (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gap[] semantics, hop field, contradictions[], and timing expectations. It also covers auth prerequisites and alternatives, making the tool self-contained for correct invocation.

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

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

Both parameters are fully documented in the schema with 100% coverage, including the enum meanings for 'depth' and the open-ended nature of 'question'. The description adds no new parameter-specific details beyond the schema; it only restates depth behavior in prose. Baseline 3 is appropriate because the schema carries the semantic load.

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

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

The description clearly states it performs 'Grounded multi-source research across Pipeworx's 1461 STRUCTURED data sources' in one call, explicitly distinguishing from open-web search. It names sibling ask_pipeworx as the alternative for single lookups, and gives example use cases like 'compare X and Y's regulatory + financial exposure'. The action is specific and the scope is well-defined.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It also states it is 'Best for broad/multi-part questions over structured data', making inclusion/exclusion criteria 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?

Annotations already mark it read-only and idempotent. The description adds valuable detail: returns top-N tools with full schemas and curated examples, ready to call directly. No contradictions.

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

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

Starts with a clear one-liner, then expands with relevant details and examples. Slightly verbose in listing data domains, but each sentence adds value.

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

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

Given no output schema, the description explains return format and usage well. Covers aliases, examples, and when to call. Lacks error cases, but acceptable for a read-only discovery tool.

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

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

Input schema already covers parameters and aliases with 100% coverage. Description adds examples and clarifies the query is natural language, but does not significantly extend meaning beyond the schema.

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

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

The description clearly states the tool finds tools by describing data/task, with specific examples. It implies its role as a discovery tool distinct from siblings ('Call this FIRST'), but does not explicitly name alternatives, so it falls short of a perfect 5.

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

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

Provides clear guidance: 'Call this FIRST when you have many tools available' and 'Use when you need to browse, search, look up, or discover'. Lacks explicit when-not-to-use or alternative tool names, but the context is strong.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it explains the patent soft-fail after May 2025, the data sources (SEC EDGAR, XBRL, USPTO, GDELT/GNews, GLEIF), and the parallel fan-out nature. 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 somewhat long but each sentence serves a purpose. It front-loads with example natural language queries, then lists technical details and constraints. Every sentence earns its place, though it could be slightly more compact by removing the explicit examples list.

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

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

Given only 2 parameters and no output schema, the description is complete. It explains what the tool returns (cik, recent_filings with URIs, fundamentals, patents, news, LEI), how it handles potential issues (patent soft-fail), and what inputs are valid. There's no missing information for an agent to use this tool correctly.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: it explains that the type parameter is currently limited to 'company' (with future plans for person/place), and for value it clarifies that ticker or CIK is expected, and explicitly states names are not supported. This adds user-facing guidance.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company. It uses specific verbs like 'brief me on', 'research', and lists the exact data points returned (CIK, filings, fundamentals, patents, news, LEI). This distinguishes it from siblings like compare_entities or deep_research.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also provides a clear exclusion: 'names not supported (use resolve_entity first if you only have a name).' This gives precise when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructive and idempotent behavior. Description adds context about clearing sensitive data, which is valuable beyond structured fields.

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

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

Two sentences, front-loaded with action and resource. No wasted words.

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

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

For a simple delete operation with one parameter, the description fully covers when and how to use it.

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

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

Schema coverage is 100%, and description does not add additional meaning to the 'key' parameter beyond what the schema provides.

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

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

Description explicitly states 'Delete a previously stored memory by key' which clearly identifies the action and resource. Distinguishes from tools like 'remember' and 'recall'.

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

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

Explicitly specifies when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with 'remember' and 'recall', guiding against misuse.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by detailing the process (fetches page, extracts info, emits markdown) and the output format ('single text blob ready to drop at site-root/llms.txt'), 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?

Description is three sentences with no waste. First sentence states primary action, second adds process details, third lists use cases. All sentences are essential and informative.

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 parameter count (2), no output schema, and rich annotations, the description sufficiently covers what the tool does, its process, and output format. It could briefly mention error handling or URL validation, but is complete enough for an agent to use correctly.

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

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

Schema description coverage is 100%, so the description does not need to duplicate parameter definitions. However, it adds context by explaining the output format (standard llms.txt markdown) and the purpose of the generated file, aiding in understanding parameter relevance.

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

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

The description uses specific verb ('generate') and resource ('llms.txt file'), clearly stating the action and output. It distinguishes from siblings by specifying its unique function of generating an AI crawler indexing file, which is not covered by any other tool in the sibling 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?

The description provides three explicit use cases (client indexing, personal project, competitor auditing) that guide when to use the tool. However, it does not mention scenarios where the tool should not be used or provide alternative tools, though none are obvious from the sibling list.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by stating the tool is 'Keyless' (no auth) and by detailing the return fields (summary, details, aliases, etc.), providing behavioral context beyond annotations. No contradictions.

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

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

Two sentences, front-loaded with action and examples. Every word earns its place—no fluff. Efficient and clear.

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 fully covers what the tool does and returns. It lists all key return fields, making it complete for the agent to understand the tool's utility.

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

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

Schema description coverage is 100% for the single 'id' parameter. The description adds meaning by giving specific examples, clarifying OSV ID format, and mentioning that IDs like 'GHSA-jf85-cpcp-j695' are valid, going beyond the schema's generic description.

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

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

The description clearly states the tool retrieves full detail for a single vulnerability by OSV ID, with examples of valid IDs and a list of returned fields. It is specific and actionable, but does not explicitly differentiate from sibling tools like query_package_vulns, so it gets a 4.

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

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

The description provides no guidance on when to use this tool versus alternatives (e.g., query_package_vulns for listing vulnerabilities). It lacks usage context or exclusions, so it scores a 2.

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

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

Annotations already provide readOnlyHint and idempotentHint. Description adds that it returns only the caller's subscriptions and specific fields, which is useful 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?

Two sentences, front-loaded with purpose and return format, followed by usage guidance. No extraneous 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?

For a simple read-only list tool with one optional parameter and annotations covering safety, the description fully covers what returns, when to use, and default behavior.

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

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

Schema covers 100% of the single parameter 'include_inactive' with its own description. Description adds no additional parameter details beyond implying active subscriptions by default.

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

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

Clearly states it lists the caller's active subscriptions and enumerates return fields. Distinguishes from siblings like 'subscribe' and 'unsubscribe' by specifying its purpose as review and id 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?

Explicitly advises when to use: 'before adding more or to find an id to cancel.' Provides clear context but no explicit when-not-to-use, though not necessary for this tool.

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

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

Annotations are all false, so the description carries full responsibility. It discloses the claim_token return/read-back flow, the daily rate limit of 5 per identifier, that it's free and doesn't count against tool-call quota, and that the team reads digests daily. This provides rich behavioral context that annotations cannot convey.

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 lengthy, every sentence earns its place: purpose, trigger conditions, exclusion, token mechanics, rate limit, and cost. It is front-loaded with the aim, and dense with actionable information without filler. For this tool's complexity, the length is fully justified.

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

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

The description covers purpose, when-to-use, when-not-to-use, token-based follow-up, rate limiting, and cost, while also handling the absence of an output schema by explaining what the tool returns (claim_token). It is thorough enough for an agent to invoke correctly and understand consequences without any further context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the claim_token round-trip pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed') and instructing users to frame feedback around Pipeworx tools/packs rather than raw prompts, which complements the schema's per-parameter descriptions.

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

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

The description opens with a clear, specific statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates the feedback categories (bug, feature, data_gap, praise) and clearly differentiates this from sibling tools like ask_pipeworx or subscribe by framing it as the dedicated feedback channel.

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 the tool ('Use when a tool returns wrong/stale data...'), provides a concrete exclusion ('ONLY for tools served by this Pipeworx connection... file it with that server instead'), and gives practical guidance on what to describe and what to avoid (don't paste the end-user's prompt). This goes far beyond basic usage hints.

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

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

Annotations declare readOnlyHint, but description adds crucial behavioral details: caching (5min-1h), data source (CF analytics-engine), PII handling, and data shape (pack, tool, count). No contradiction with annotations.

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

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

Description is concise: first sentence states purpose, then bulleted use cases, then additional context. Every sentence adds value without redundancy. Front-loaded with key information.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description fully covers what the tool returns, how it works, caching behavior, and appropriate use cases. No gaps.

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

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

Schema covers the one parameter 'window' with enum and description. Description adds value by explaining the trade-off between short and long windows ('Shorter windows surface what's hot right now; longer windows show steady-state demand.').

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 returns top tools, packs, and call volume, using specific verbs like 'Returns' and listing the resources. It distinguishes itself from siblings like 'discover_tools' or 'ask_pipeworx' by focusing on trending usage from other agents.

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?

Description explicitly lists three use cases (discovering hot data sources, confirming canonical tools, aligning use case) and explains window choices. Does not explicitly state when not to use, but the guidance is clear for a simple read-only tool.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds rich behavioral context: monotonicity violations, partition checks, Jaccard similarity, placeholder filtering, fill check against live depth. No contradictions.

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

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

The description is lengthy but every sentence earns its place given the tool's complexity. It is front-loaded with purpose and structured with clear paragraphs for each mode.

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 response format (opportunities[] with fields, partition_check details, fill_check). It also covers edge cases like skipped_low_similarity and placeholders.

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

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

Schema coverage is 100%, but the description adds meaningful context: explains event slugs with examples, notes that full URLs are accepted, and clarifies topic as a seed question for cross-event scanning.

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 a specific verb-resource pair (find arbitrage opportunities) with clear distinctions between no-arg, event, and topic modes. It differentiates from siblings like polymarket_fill_risk.

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

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

Explicit when-to-use guidance for each mode: no args for trending scan, event for specific market, topic for cross-event scanning. Also references polymarket_fill_risk for custom sizing, providing clear 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 (readOnlyHint, idempotentHint) already signal safety, but the description adds exceptional behavioral detail: three model family mechanics, caching behavior ('Cached 1h at the KV level keyed on all knobs'), response structure with diagnostics, and a note on the unreliability of Fed signal data. No contradictions with annotations.

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

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

The description is long but well-structured, front-loading the main purpose and then detailing segments, parameters, and response format. Each section adds value, though some details (e.g., per-sport α values) could be summarized. Still, it is efficient for the complexity.

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

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

Given the tool's complexity (9 parameters, no output schema, multiple segments), the description covers all necessary context: segment explanations, tradeable-edge filters, response structure, diagnostics, caching, and Fed bet handling. No gaps remain for an agent to understand how to invoke and interpret results.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description elaborates on some (e.g., slippage_pp explains typical bid/ask), but mostly repeats schema descriptions. It adds value for a few parameters (e.g., min_partition_leg_kelly usage) but does not significantly enhance meaning beyond the schema, justifying a baseline 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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' and frames it as 'what should I bet on today'. It distinguishes itself from siblings by detailing three unique model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) not covered by other tools like polymarket_arbitrage.

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 tool usage, including parameter knobs for filtering (e.g., min_liquidity, max_spread_pp) and explains when to adjust slippage. It notes that Fed bets are excluded from ranking with a rationale. However, it does not mention when NOT to use this tool in favor of alternatives (e.g., polymarket_arbitrage), which would have earned a 5.

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

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

Annotations declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description goes beyond by detailing that the tool reads from daily snapshots, provides time-series data, computes trends (new, widening, stable, decaying) and decay rates, tracks expired opportunities, and mentions limitations like the 60-day TTL and that decay numbers are from daily closes, not intraday. This adds significant 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?

The description is fairly concise given the complexity of the output. It is front-loaded with the core purpose, then details parameters, response structure, and limitations. Some sentences are dense, but every part adds value. Could be slightly shorter, but overall well-structured.

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

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

Given the absence of an output schema, the description thoroughly explains the response fields: tracked[], expired[], and snapshot_dates[]. It covers limitations and data sources. However, it does not define 'edge_pp_net' in detail (only mentions 'net of default slippage'), which might be insufficient for complete understanding. Otherwise, it is comprehensive.

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

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

Schema description coverage is 100%, so baseline is 3. The tool description repeats the parameter names and defaults, adding slight context (e.g., 'max 30' for days, but schema already says 'clamp 2-30'). It does not elaborate further on parameter usage or formats beyond what the schema provides, so no extra value beyond 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 the tool provides 'edge persistence and decay telemetry' and answers 'how long has this edge existed and is it shrinking?', using a specific verb ('track') and resource (edges over time). It distinguishes from sibling tools like polymarket_edges by focusing on time-series analysis rather than current edges.

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: to assess whether an edge is stale by checking its history. It includes the example that a 3-week-old wide edge is different from a fresh one. However, it does not explicitly state when not to use it or name alternative tools, though the context with siblings and the described limitations provide some guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context beyond annotations: it walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns about thin legs and forced directional risk. It explains that partial basket fills convert an arb into an unhedged directional position. 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 fairly long but densely packed with necessary information. It is well-structured with sections for single-market and basket modes, and a usage note. Every sentence adds value, though a slightly more compact presentation could be achieved without losing clarity. Still, it is efficient given the complexity.

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

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

The tool has 4 parameters, no output schema, and two complex modes. The description comprehensively covers inputs, behavior, and return fields (e.g., top_of_book, vwap_fill_price, slippage_pp, thin_legs). While it doesn't provide a structured output schema, it lists the key output fields and explains their meaning. For the complexity, this is nearly 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%, so baseline is 3. The description adds substantial meaning: it explains that `market` and `event` select modes, defaults for `side` (auto for basket), and the dual interpretation of `size_usd` (spend vs target proceeds vs settlement notional). It also provides constraints (clamp 10–1,000,000). This goes well beyond the schema descriptions.

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

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

The description clearly states it performs a realizable-vs-theoretical edge check against live CLOB order-book depth. It explains two distinct modes (single-market and basket) and explicitly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this tool before those actions. The verb+resource combination is specific and unambiguous.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why not using it leads to problems (theoretical overround not capturable, partial fills convert arb to directional position). It contrasts the two modes and their prerequisites (market vs event).

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 extensively discloses behavior beyond annotations: compatibility_warning conditions, temporal alignment impact, skipped cross types, and the fact that most pre-mapped topics return warnings. This adds significant value to the agent's understanding of tool behavior.

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

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

The description is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and uses all-caps for emphasis. It is slightly verbose but every sentence adds value.

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

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

Given no output schema, the description fully explains the response format (prices, spreads, safety fields) and all edge cases. It covers everything an agent needs to understand the tool's output and limitations.

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 covers all three parameters (100% coverage). The description adds semantic meaning: lists the 10 topic shortcuts, explains that explicit tickers override topic-mapped sides, and gives examples. This exceeds the schema's information.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishes two modes (topic shortcuts and explicit tickers), and explains output fields. It differentiates from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description provides explicit guidance on when to use the tool and warns when outputs may be unreliable (e.g., temporal misalignment, compatibility warnings). It implies alternatives (e.g., polymarket_arbitrage for intra-venue arb) but does not explicitly name them.

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

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

Adds behavioral context beyond annotations: up to 1000 entries per call, input format (array of specific shapes), return type (vuln IDs), and keyless operation. No contradiction with annotations.

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

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

Every sentence is necessary and informative. The description is front-loaded with the core purpose, then details. No redundant or weak 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 simple one-parameter tool with full schema coverage and an output schema, the description covers input format, usage context, limitations, and how to get full details. No gaps given the 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?

The description explains the parameter structure in plain language, including the two allowed shapes ({package:{name,ecosystem}, version?} or {commit}), which adds meaning beyond the schema description. With 100% schema coverage, this is solid value.

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

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

The description clearly states the verb ('batch query'), resource ('vulnerabilities against OSV.dev'), and distinguishes from siblings like 'get_vulnerability' and 'scan_dependency' by specifying 'SBOM-style' workflows and the limit of 1000 entries per call.

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 it's for 'SBOM-style scan every dependency in this lockfile' workflows, advises using 'get_vulnerability' for full details per ID, and notes it's keyless. Could mention when not to use (e.g., single query) but provides sufficient guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. Description adds 'Keyless' (no auth) and mentions return format ('same compact vuln summary array'), which is useful but not essential 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?

Two sentences, no fluff, front-loaded with purpose. Every word adds value.

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

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

Tool is simple with one parameter and no output schema. Description provides enough context (use case, return format, keyless) to use effectively. Annotations cover behavioral aspects.

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?

Only one parameter 'commit' with 100% schema description coverage. Description does not add additional semantic detail beyond the schema, but the schema alone is sufficient. Baseline 3 applies.

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

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

Description clearly states the verb (find), resource (vulnerabilities affecting a specific commit), and method (via OSV.dev). It distinguishes from sibling tools by specifying the use case of 'pinned commit hash' versus 'released version'.

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?

Description explicitly states when to use this tool ('when you have a pinned commit hash rather than a released version'), providing clear context for selection among siblings. However, no explicit when-not or alternative tool names are given.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds output format details ('compact summary array') and notes it is keyless (no auth), going beyond the annotations.

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

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

Two sentences front-load the core purpose and usage, with no wasted words. Every sentence earns its place.

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

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

Given the tool's simplicity, annotations, and no output schema, the description covers the main aspects: purpose, filtering, and output shape. It could mention rate limits or pagination, but it's sufficient for a straightforward query tool.

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

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

Schema coverage is 100% with examples. The description adds value by noting that omitting version returns all vulnerabilities for the package and that the tool is 'Keyless', which provides additional context beyond the schema.

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

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

The description clearly states it finds vulnerabilities for an open-source package, with optional version filtering, via the OSV.dev database. It distinguishes from siblings like get_vulnerability (single vuln) and scan_dependency (project-level).

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 omit the version parameter to get all vulnerabilities, providing clear usage context. It does not explicitly exclude alternatives, but the purpose is well-scoped.

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. The description adds valuable context like scoping ('anonymous IP, BYO key hash, or account ID') and the ability to list all keys by omitting the argument, which goes beyond what annotations provide.

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

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

Four sentences, each earning its place: action, usage examples, scoping, pairing with siblings. Front-loaded with the most critical information, no wasted words.

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

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

Given the tool's simplicity, the description covers the typical use cases. It explains the main actions (retrieve value or list keys), scoping, and relationships. Lack of output schema is mitigated by the straightforward nature. Could mention error handling (e.g., key not found) but not critical.

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 the parameter with a description. The description reinforces the behavior (omit to list all keys) and gives an example key value ('user_research_topic'), adding practical meaning beyond the schema.

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

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

The description uses a specific verb ('Retrieve' or 'list') and resource ('value previously saved via remember' or 'all saved keys'). It clearly distinguishes the tool's core actions and ties to sibling tools like 'remember' and 'forget', making the purpose unambiguous.

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

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

The description provides concrete usage scenarios ('the user's target ticker, an address, prior research notes') and explicitly pairs with 'remember' and 'forget', implying when to use. It lacks explicit exclusions (e.g., when not to use, or alternatives among siblings) but is clear enough for practical use.

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

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

Annotations provide readOnlyHint, idempotentHint, etc. Description adds context on mark_read behavior (flags events read) and polling suitability, enhancing transparency beyond annotations. However, there is a potential contradiction with readOnlyHint as mark_read modifies state.

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

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

Description is concise and front-loaded with the main action. Each sentence adds value, though could be slightly more terse. 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?

Covers return fields, filtering, mark_read behavior, polling, and alternative access method. No output schema exists, but description sufficiently explains what the tool returns. Missing error/rate limit info, but overall comprehensive for a read-only tool.

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

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

Schema coverage is 100%, but description adds practical context for each parameter (e.g., 'Filter by type (e.g. "sec_8k")', 'ISO timestamp', 'flag returned events read'), improving comprehension beyond schema descriptions.

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

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

The description clearly states 'Pull fired events from your subscription feed' with specific verb and resource. It distinguishes from sibling tools by focusing on retrieving alerts, not managing 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?

Mentions polling suitability and alternative GET endpoint for scripts/dashboards, but does not explicitly state when to use this tool over sibling tools or provide exclusion criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, and nondestructive nature. Description adds operational details: fans out to multiple sources, fallback logic, window-based querying, return structure (changes grouped, total_changes count, citation URIs), and specific behavior for patent data (soft-fail). No contradiction with annotations.

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

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

Description is a single paragraph that efficiently packs purpose, usage, parameter guidance, and behavioral notes. Every sentence is informative; no fluff. Front-loaded with query 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?

Given the tool's complexity (multi-source, fallback, various input formats) and lack of output schema, the description fully explains return structure, source behavior, and parameter details. It also references the alternative tool entity_profile for completeness.

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

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

Schema coverage is 100% with good descriptions. The description adds extra context for 'since' (relative shorthand like '30d'), explains that 'type' only supports 'company', and clarifies that 'value' accepts ticker or CIK. This adds meaning beyond the schema.

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

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

The description clearly states the tool provides a change feed for a company in a specified time window, listing data sources (SEC EDGAR, GDELT/GNews, USPTO) and example queries. It explicitly distinguishes from sibling entity_profile by advising when to use that tool instead.

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 examples and context (e.g., 'What's new with X'), advises alternative entity_profile for static profiles, and explains fallback behavior (GDELT→GNews) and soft-fail for patents. The description tells when to use the tool and when not to.

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

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

Annotations indicate idempotentHint=true and not read-only or destructive. The description adds valuable context: key-value pairing scoped by identifier, persistence differences between authenticated and anonymous users. 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 concise (4 sentences), front-loaded with the primary purpose, and structured logically. Every sentence adds value without redundancy.

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

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

Given the simplicity of a key-value storage tool and no output schema, the description covers usage, scoping, and persistence adequately. However, it omits mention of key overwrite behavior or data limits, which could be useful.

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 provides high-level examples but does not add significant detail beyond what the schema's property descriptions already provide for 'key' and 'value'.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later' – a specific verb and resource. It also distinguishes itself from sibling tools 'recall' and 'forget' by explicitly naming 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 usage guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also mentions pairing with recall/forget, but lacks explicit when-not or alternative comparisons.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior, and the description adds substantial context beyond that: source-labelled identifiers, explicit unresolved identifier reporting, graceful degradation when GLEIF/OpenFIGI are unavailable, and internal cascading lookups. No contradiction with annotations.

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

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

The description is long but front-loaded with practical examples and organized by entity type. Most sentences add unique value, but it is dense and could be slightly tightened. It remains informative without irrelevant 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?

Without an output schema, the description successfully explains what the agent can expect: source-labelled identifiers, unresolved items, drug citation format, and behavior under partial service failure. It covers supported types, input variants, and output characteristics, making it complete for tool 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 schema covers both parameters with 100% description coverage, so the baseline is 3. The description adds meaningful detail beyond the schema: accepted input formats for companies (ticker, CIK, ISIN, name) and drugs (brand/generic), plus special behavior like ISIN resolving to the legal entity via GLEIF. This elevates the score.

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

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

The description clearly states that resolve_entity maps user-spoken names to canonical/official identifiers, with specific trigger phrases like 'What's the ticker for...' and 'look up the ID for...'. It distinguishes itself by noting it should be used when other tools require an ID, setting it apart from sibling tools like entity_profile and compare_entities.

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: 'Use FIRST whenever you have a name but need an ID.' It also gives examples of supported types and input forms. However, it does not mention specific alternative tools or describe when not to use it, so it stops short of a perfect score.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral details: probes each entity, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, signal density. This enriches the behavioral understanding beyond annotations.

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

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

Three sentences, front-loaded with the main purpose. Each sentence contributes unique value: purpose, method, use case/example. No redundant or verbose language.

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 4 parameters (1 required), no output schema, but the description explains the output format (ranked list with score, confidence, signal density). It sufficiently covers what the tool does and returns, though it could mention any limitations (e.g., maximum entities).

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 all parameters. The description adds meaningful semantics beyond the schema, such as noting that the first entity is treated as the 'subject' for narrative while the rest are competitors, and that context is applied uniformly.

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 'Compare' and the resource 'AI visibility across multiple entities side-by-side'. It distinguishes from siblings by mentioning the specific probing with ai_visibility_check and the ranking/scoring output, differentiating it from general comparison tools like compare_entities.

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 use ('competitive AI-marketing audits') and an example ('does Claude know about us as well as our competitors?'). It implies when to use but does not explicitly state when not to use or mention alternative tools like ai_visibility_check for single entities.

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 the tool as read-only, open-world, and idempotent. The description adds value by explaining the fan-out behavior across deps.dev and bundlephobia, the return format (summary block, per-advisory detail, links, alternative versions), and handling of partial failures including a timeout warning (5-30s) and the sources_failed field.

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

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

The description is fairly long but tightly packed with essential information. It front-loads the core purpose and uses clear structure (e.g., listing return fields, noting ecosystem scope). Could be slightly streamlined but achieves high information density.

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

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

Given the absence of an output schema, the description compensates by listing the return fields (is_latest, license, etc.), per-advisory detail, links, and alternative versions. It also covers edge cases like partial failures and timeouts, making the tool's behavior fully comprehensible.

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

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

Schema coverage is 100%, so the description adds meaning beyond the schema by explaining that the 'version' parameter defaults to the latest published version when omitted and that scoped packages like '@types/node' are accepted.

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

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

The description clearly states it performs a composite check for deciding whether to add an npm package, covering license, advisories, version history, and bundle size. It distinguishes from sibling tools by specifying 'NPM ecosystem only in v1' and directing other ecosystems to a different endpoint.

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

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

The description explicitly states when to use the tool: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also explains when not to use it (other ecosystems) and provides alternatives (deps.dev:version directly).

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

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

Discloses truncation at 200K chars, embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, and output containing offsets and scores. Adds value beyond readOnly/idempotent 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?

Efficient single paragraph with clear front-loading: purpose first, then usage, then technical details. Every sentence adds value; 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?

Comprehensively covers technique, use case, pairing, limitations, output details (offsets, scores). No output schema but description sufficiently explains return values.

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

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

Schema description coverage is 100%, so baseline is 3. Description provides example queries, clarifies max chars for text, and explains limit parameter effect. Adds meaningful examples.

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

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

Clear verb and resource: 'semantic search INSIDE a fetched record'. Differentiates from sibling ask_pipeworx_grounded by contrasting retrieval vs. within-document search.

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: 'Use when the record is too big to cram into the prompt'. Describes context-saving and offset verification benefits. Pairs with ask_pipeworx_grounded for grounded responses.

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?

Extends beyond annotations with details on return value, account requirement, type-specific behaviors, delivery channel constraints (e.g., SMS cap, webhook HMAC). No contradictions.

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

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

Front-loaded with main action and return value. Each sentence adds value; slightly long due to extensive examples but appropriate for complexity.

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

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

Covers all essential aspects: creation action, return value, prerequisites, multiple types with examples, delivery channels and their limits. No output schema, but return value described.

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?

Adds significant value over schema: explains each type with examples, details params structure per type, and clarifies delivery sub-properties with constraints (e.g., phone verification, webhook signing).

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

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

Clearly states verb 'Create', resource 'subscription', and scope 'proactive monitoring to a live-data event stream'. Distinguishes 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?

States prerequisite (Pipeworx OAuth account) and implicitly differentiates from list/unsubscribe. Lacks explicit 'when not to use' but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds that results are drawn from the live catalog and returns specific categories, providing 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?

Description is relatively long but front-loaded with example queries, and every sentence adds useful detail. It's well-structured but slightly verbose; could be tightened slightly without losing clarity.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description fully covers purpose, usage, and parameter behavior. It explains the output format (categories with tool+argument) sufficiently.

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 optional parameter. Description adds value by explaining that omitting the topic gives full spread and passing it focuses the results, going beyond the schema's description.

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

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

Description clearly states the tool returns category-bucketed example questions and is the onboarding entry point. It distinguishes itself from sibling tools like ask_pipeworx and deep_research by focusing on suggesting 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?

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and gives example queries. While it doesn't state when not to use it, the context and examples make the usage clear.

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

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

Annotations indicate not destructive; description adds that row is deactivated (not deleted), ownership enforcement, and historical events remain. No contradiction.

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

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

Two efficient sentences with no redundancy. Front-loaded with action and key constraints.

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 simple tool (1 param, no output schema), description covers behavioral outcomes, ownership, and links to related tool (recent_alerts) for historical data. Complete for agent use.

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

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

Schema covers id parameter fully (100% coverage) with description 'Subscription id (uuid) returned by subscribe.' The tool description does not add beyond the schema, baseline 3 applies.

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

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

Clear verb 'Cancel' with specific resource 'subscription by id'. Distinguishes from siblings (list_subscriptions, subscribe) by describing ownership enforcement and deactivation behavior.

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

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

States ownership enforcement (only cancel own subscriptions) which implies use when you own the subscription. Mentions deactivation (not deletion) and connection to recent_alerts, but does not explicitly name alternative tools for full deletion.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses critical behavioral nuances: the two verification pipelines, exact percent-delta math for financial claims, and the distinction between could_not_verify (check did not happen) and unsupported (no source covered). This prevents misinterpretation and clearly explains what the tool does internally.

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 information-dense; every sentence contributes to purpose, usage, behavior, or return-value interpretation. It is front-loaded with examples and clearly structured. Although slightly lengthy, the complexity of the tool justifies the length.

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

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

There is no output schema, so the description compensates by enumerating possible verdicts (confirmed, refuted, etc.) and explaining the return value (actual value with citation, reasoning). It also covers edge cases and pipeline routing, giving an agent everything needed to invoke and interpret results 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% — both claim and tolerance_pct are well-documented in the schema. The description itself does not add significant parameter-level detail beyond what the schema already provides; it only indirectly alludes to math and behavior. Thus the baseline of 3 applies.

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

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

The description immediately defines the tool as natural-language claim verification against authoritative sources, with explicit query examples. It distinguishes the tool from siblings by detailing a dual pathway for company-financial claims (SEC EDGAR + XBRL) versus all other claims (grounded pipeline) and notes it replaces 4-6 sequential calls, making its niche clear.

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

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

The description provides an explicit usage trigger: 'Use whenever the agent needs to check whether something a user said is factually correct.' It explains the automatic routing for claim types, gives parameter guidance (e.g., setting tolerance_pct 1–2 for hallucination detection), and instructs callers on how to interpret could_not_verify versus unsupported — turning the response into actionable guidance.

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