Jisho

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

Annotations already indicate idempotent, read-only, non-destructive behavior. The description adds value by explaining the default model, optional Anthropic probing with BYO key and cost implications, and the return structure.

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

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

Two concise sentences that front-load the main action and then add important details and use cases without any fluff.

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

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

Given no output schema, the description thoroughly explains the return format (per-model score, confidence, signals, raw_response + combined view). It also covers model options, cost, and typical use cases. No gaps identified.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra context like default model being free, `_apiKey` being passed straight through, and `context` helping disambiguation, which enhances parameter understanding.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about an entity and scoring visibility per model. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on per-model 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 usage context (AI-marketing audits, pre-launch checks, competitive monitoring) but does not explicitly mention when not to use it or name alternative tools for similar tasks.

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 non-destructive behavior. The description adds useful behavioral context: it is a router/aggregator that auto-fills sub-tool arguments and returns stable citation URIs. It also implies hallucination risk by recommending ask_pipeworx_grounded when an answer 'must not hallucinate'. 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 core content is useful and front-loaded, but the same block of domain list, trigger phrases, examples, and 'START HERE' is repeated multiple times. This repetition makes the description unnecessarily long and fails the standard that every sentence should earn 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?

The description covers purpose, usage, trigger examples, alternative tools, and the response shape including structured answers and citation URIs. Since there is no output schema, mentioning the return format adds value. Minor gaps like latency or failure behavior are acceptable given the read-only, open-world annotations.

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

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

Schema description coverage is 100%, with all parameters documented as aliases of the single 'question' parameter, so the description does not need to repeat them. The note that the tool 'fills arguments' is helpful but does not add parameter-level semantics beyond the schema.

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

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

The description clearly states that ask_pipeworx routes natural-language questions to one of 5,738 tools across 1,499 verified sources, fills arguments, and returns a structured answer with pipeworx:// citation URIs. It is specific about the resource and behavior and is easily distinguishable from deep_research and ask_pipeworx_grounded.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions,' and gives exact trigger phrases like 'what is', 'look up', 'find', and 'get the latest'. It also names alternatives: ask_pipeworx_grounded for anti-hallucination answers, deep_research for broad/multi-part questions, and news packs for breaking-news coverage.

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

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

The annotations already declare read-only and idempotent behavior, and the description adds valuable context: candidate routing improvements are enabled live, no candidate is currently active, it currently matches ask_pipeworx exactly, and it has no fallback because it is a full working router. This gives the agent an accurate behavioral model beyond the structured 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 packed with necessary context: beta status, current candidate state, usage instruction, comparison behavior, and fallback clarification. Every sentence earns its place, and the most important framing is front-loaded.

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

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

For a router-style tool with a single required question parameter and no output schema, the description addresses purpose, current behavior, usage, and fallback behavior. The agent has enough information to invoke the tool correctly and know what to expect.

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

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

Schema description coverage is 100%, and the input schema already explains that q, text, input, query, and prompt are aliases for question. The description only says it has the same arguments as ask_pipeworx, which adds little beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies this as a beta version of ask_pipeworx acting as a universal router with the same 5,738 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by its candidate routing improvements, so an agent can tell exactly what this tool is for.

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

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

The description explicitly says to use it like ask_pipeworx when the newest routing is desired, and it explains that results are compared against the stable router to decide what merges. It does not explicitly enumerate when not to use it or mention the grounded alternative, so it stops just short of full when/when-not 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses the refusal mechanism with specific refusal_reason values, the output shape, and the extra LLM call cost. It also explicitly states that answers are extracted only from tool results, which is critical behavioral context. No contradiction with annotations.

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

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

The description is dense but well-organized: purpose first, then internal routing behavior, return shape, usage guidance, and cost tradeoff. Every sentence adds meaningful information, though it is slightly long and could be tightened without losing key details.

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 there is no output schema, the description compensates by detailing the success response, refusal response, refusal reasons, and practical usage boundaries. It also mentions the alternative tool and cost implications, making it fully actionable for an agent deciding whether and how to call it.

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

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

Schema coverage is 100%, with the schema already documenting the question parameter and its aliases. The description doesn't add details about how to phrase or format the question, but the schema carries that burden. 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 a 'hallucination-resistant answer mode' for high-stakes reads, and explicitly distinguishes it from sibling ask_pipeworx by emphasizing evidence extraction and refusal behavior. It states a specific verb ('extracts the answer'), a resource (Pipeworx's tool network), and a unique behavioral scope.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete domains. It also names ask_pipeworx as the fallback for casual lookups and explains the cost tradeoff, making the routing decision unambiguous.

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

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

The description extensively details behavioral traits beyond annotations: fan-out patterns, response shapes, resolver contract, parent event extractor, news fields, safety mechanisms, and resolution-rule risk. Annotations confirm readOnly and idempotent, and the description adds deep context about blocking paths and edge cases.

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

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

The description is lengthy but well-structured with paragraphs covering different aspects. It could be slightly more concise, but the density of valuable information justifies its length. Front-loading key points helps quick understanding.

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

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

Despite lacking an output schema, the description completely explains return values, edge cases, and safety mechanisms. It covers result.market, result.analysis, result.evidence, resolver contract, parent event, news fields, and more. The description is comprehensive given the tool's complexity.

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

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

The input schema has 100% description coverage, and the description adds value by explaining each parameter's semantics: depth behavior (quick vs thorough), market input formats (slug, URL, question text), and include_raw effect on response size. This goes 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 the tool's purpose: researching a Polymarket bet by pulling Pipeworx data in one call. It specifies the action, resource, and method, distinguishing it from sibling tools like ask_pipeworx or polymarket_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 explicitly states when to use the tool: for queries like 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. It provides examples of fan-out and classifiers, but does not explicitly mention when not to use it or list alternatives.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds beyond: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorted results, and citation URIs. 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?

Front-loaded with trigger phrases, then core functionality, then type-specific details, then sorting and output notes. 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?

Covers both entity types, data sources, sorting behavior, and output format (paired data + citation URIs). No output schema, but description sufficiently explains return structure. Complete for a comparison tool of this complexity.

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

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

Schema coverage is 100%, so schema documents both parameters. Description adds valuable domain context: type='company' pulls specific financial metrics and handles fiscal years; type='drug' pulls FAERS counts. Also clarifies values format with examples and limits.

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

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

The description clearly states the tool does side-by-side comparison of 2-5 companies or drugs in one parallel call. It uses specific verbs like 'Compare', 'rank', 'head to head' and distinguishes from siblings like entity_profile and lookups by emphasizing parallel execution.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides trigger phrases (e.g., 'which is bigger'). It also quantifies the replacement value (8-15 sequential lookups), giving clear when-to-use context.

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

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

Annotations (readOnlyHint=true, idempotentHint=true) already cover the safety profile, so the description correctly focuses on additive behavioral context: account/auth requirements with a paid tier for 'thorough', latency expectations ('15-60s ... up to ~90s'), the 'never invented' gaps[] guarantee, contradictions[] scanning for standard/thorough, citation_uri included only when resolvable ('a citation you get back is always fetchable'), and semantic excerpting ('not head-truncated'). This substantially enriches what annotations alone convey, with no contradiction to them.

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

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

The description is long but front-loaded with the most critical gate (account required, signup link) and nearly every sentence adds distinct value — sources, facets, output packet shape, latency, citation guarantees. However, there is some redundancy: contradictions[] is mentioned both here and in the schema's depth description, the paid-tier requirement appears twice, and the ask_pipeworx alternative is stated more than once. Dense and useful, but not maximally economical.

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 correctly carries the full burden of explaining return expectations, and it does so thoroughly: findings packet contents (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gap recovery behavior, contradictions[], hop field, and citation_uri fetchability. It also covers prerequisites (sign-in, paid plan), latency, data-source scope, depth semantics, and exclusions. For a complex research tool, essentially everything an agent needs to invoke and interpret the result is present.

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

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

Schema coverage is 100% and the schema's depth description already explains each enum value, establishing a baseline of 3. The description adds meaning beyond the schema by explaining the behavioral mechanism of the depth values ('depth:"standard" re-angles unanswered gaps (gap recovery); depth:"thorough" additionally chases the best leads from the first pass') and confirming that broad/multi-part questions are valid for the question parameter. It complements rather than repeats the schema, meriting a 4.

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

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

The description states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1499 STRUCTURED data sources ... in ONE call', and details the mechanism ('Decomposes your question into focused facets, routes each to the right one of 5,738 tools IN PARALLEL'). It clearly differentiates from siblings with explicit disclaimers ('this is NOT open-web search', 'For a single lookup use ask_pipeworx'), so an agent can distinguish it from ask_pipeworx, compare_entities, and entity_profile without opening their schemas.

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?

Usage guidance is explicit and actionable: 'If you are not signed in, use ask_pipeworx instead', 'Best for broad/multi-part questions over structured data', and 'For a single lookup use ask_pipeworx'. It even names a negative case — 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx ... deep_research returns mostly empty gaps[] when the topic isn't in the structured catalog' — giving the agent both when-to-use and when-not-to-use conditions with named alternatives.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that results include full input schemas with curated examples, ready to call directly, no second lookup needed. This provides behavioral context beyond annotations, with 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 somewhat verbose but front-loaded with key information. Every sentence adds value, though slight tightening could improve conciseness. 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 tool's discovery purpose, the description fully covers what it does, when to use it, and what it returns. No output schema, but the return type (tools with schemas) is adequately 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?

Schema coverage is 100% with all properties described. The description adds value by explaining that query accepts multiple aliases (q, task, search, description) and provides examples. While not extensive, it enhances parameter understanding beyond the schema alone.

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

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

The description clearly states the tool finds tools by describing data or task, lists example domains, and distinguishes from siblings by explaining it returns top-N tools for browsing. The verb 'find tools' and resource 'tools' are specific and unambiguous.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies it is for discovery, not execution.

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

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

Annotations already declare readOnly/idempotent/openWorld, and the description adds substantial behavior beyond them: the parallel fan-out across sources, sources_used/sources_failed semantics ('an empty section is a real "no data", not a bug'), the private-company resolved:false + notes behavior, the FDA 'none is expected, not a failure' caveat, and the GDELT→GNews fallback. This is exactly the kind of interpretation guidance agents need.

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 carries real content and there is no fluff except the roadmap note 'person/place coming soon', but the entire description is one dense unbroken paragraph with no bullets, headings, or visual scansion. The return-field documentation, while valuable given the missing output schema, is dumped mid-paragraph rather than structured, hurting readability for an agent parsing the text.

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 high-complexity tool with no output schema, the description covers nearly everything needed to invoke and interpret it correctly: return shape (cik, company_name, recent_filings with URIs, fundamentals, patents, contracts, FDA, hiring, news, LEI), empty-result semantics, input formats, resolution behavior, and edge cases (private company, small-molecule-only FDA portfolio). Only minor gaps like rate limits or news time windows remain.

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

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

Schema coverage is 100%, so baseline is 3; the description earns the extra point by adding meaning beyond the schema: it states that type='company' and type='ticker' behave identically, that value accepts three forms with concrete examples, that names resolve via SEC EDGAR, and how a private-company input behaves at the result level.

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 in 'full cross-source profile of a US public company in ONE parallel call' and reinforces it with query examples ('research Acme', 'company profile for Microsoft'). It is visually distinct from the single-pack lookups it names as alternatives, so an agent can tell what it does without inspecting the schema.

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 an explicit trigger ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'). However, it does not name the sibling tools that should win in other cases (e.g., resolve_entity, lookup, scan_competitor_ai_presence), nor does it state when NOT to use this tool, so the exclusion side is left to inference.

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 destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and pairing, but does not disclose further behavioral traits beyond what annotations imply.

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

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

The description is two sentences, front-loaded with the action, and every sentence adds value. 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 single-parameter destructive tool with complete annotations, the description provides sufficient context about use cases and tool relationships.

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 mentions 'by key', which mirrors the schema's 'key' property but adds no new meaning or constraints.

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

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

The description clearly states the action 'Delete' and the resource 'a previously stored memory by key'. It distinguishes itself from sibling tools like 'remember' and 'recall' by specifying deletion specifically.

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: 'when context is stale, the task is done, or you want to clear sensitive data'. It also mentions pairing with 'remember' and 'recall', which implies alternatives.

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

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

Annotations already indicate safe, idempotent behavior. The description adds value by detailing the fetch-extract-emit process, which helps the agent understand side effects (no mutations, just reads). No contradictions.

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

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

The description is a single paragraph with no wasted words. It front-loads the core purpose, then adds behavioral detail and use cases. Could be slightly more structured but is efficient.

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

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

With no output schema, the description adequately explains the output format ('standard llms.txt markdown format', 'single text blob'). It covers input behavior (fetching, extracting) and fits within the complexity of a simple 2-parameter 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%, so the schema already documents both parameters fully (url required, max_links with default/max). The description does not add new meaning beyond the schema, resulting in a baseline score of 3.

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

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

The description clearly states the action ('generate'), the resource ('llms.txt file for any URL'), and the purpose ('so AI crawlers can index the site cleanly'). It distinguishes itself from sibling tools by being the only one dedicated to llms.txt generation.

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

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

The description explicitly lists three use cases (client indexing, personal project, competitor audit), giving agents clear when-to-use guidance. It does not mention alternatives or exclusions, but the sibling list contains many non-relevant tools, making this tool's niche apparent.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false. Description adds that it returns specific fields and focuses on active subscriptions, which aligns 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?

Two concise sentences with front-loaded action and return info, no unnecessary text.

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

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

For a simple read-only tool with one optional parameter and comprehensive annotations, the description fully covers purpose, return data, and usage 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% with a clear parameter description. The tool description does not add extra semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

Clearly states it lists active subscriptions and enumerates returned fields (id, type, params, etc.). Distinguishes from sibling tools like subscribe 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?

Explicitly advises using it to review current subscriptions before adding more or to find an id to cancel, providing clear context for when to use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety and idempotency. The description adds value by specifying the return fields (headword, common-ness, JLPT level, etc.) and input acceptances (kanji, kana, romaji, English). It does not cover potential rate limits or external API dependency, but for a simple lookup this is sufficient.

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 (3 sentences) and front-loaded with the core purpose. Every sentence provides essential information: what it does, what it returns, best use case, and accepted input formats. 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 (single parameter, no output schema) and comprehensive annotations, the description fully covers the necessary context. It explains the input, output, and intended use, leaving no significant gaps for an agent to misinterpret.

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

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

Schema description coverage is 100% for the single parameter 'word', with a detailed description. The main tool description reiterates the accepted input types ('kanji, kana, romaji, or English'), which adds no new information beyond the schema. Baseline score of 3 is appropriate as the description does not enhance parameter understanding significantly.

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

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

The description clearly states the action ('look up'), the resource ('a single Japanese or English word in the Jisho.org dictionary'), and the return format ('compact form... headword, common-ness, JLPT level, readings, meanings, parts of speech'). It distinguishes from sibling tools like 'search_words' by emphasizing single best match and compactness.

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

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

The description explicitly states the best use case: 'quick "what does this word mean / how is it read" questions'. It implicitly differentiates from broader searches (e.g., 'search_words' sibling) but does not mention specific scenarios when not to use or alternatives. This is adequate but not exhaustive.

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

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

Annotations are all false (no hints), so the description carries full burden. It discloses rate limiting (5 per identifier per day), quota exemption (free, doesn't count against tool-call quota), the claim_token mechanism for later status checks, and the human process (team reads digests daily, signal affects roadmap). This goes far beyond the minimal safety profile and gives the agent accurate 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 dense but every sentence adds operational value: purpose, when-to-use, when-not-to-use, alternative action, claim_token mechanics, message guidance, team workflow, rate limit, and quota impact. It is front-loaded with the most critical information and has no redundant filler.

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

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

For a feedback tool with no output schema, no helpful annotations, a nested context object, and a subtle claim_token follow-up mode, the description covers all necessary aspects: how to categorize feedback, what context to include, what to avoid, the token workflow, rate limits, and cost. An agent can confidently invoke this tool without further clarification.

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 parameter names and types well, but the description adds essential semantics: claim_token is for reading a previous report's status and must be passed alone; message should describe issues in terms of Pipeworx tools/packs, not paste user prompts. This guidance prevents common misuse and clarifies the intended flow beyond what the schema states.

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

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

The description opens with a specific verb+resource ('Tell the Pipeworx team something is broken, missing, or needs to exist') and immediately enumerates concrete use cases (bug, feature/data_gap, praise). This clearly distinguishes it from sibling research and utility tools, which are about retrieving or analyzing data, not providing feedback.

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 is given for each feedback type, plus a clear exclusion: if the tool came from a different MCP server, file with that server instead. It also explains the claim_token follow-up workflow, giving the agent a complete decision framework for using this tool vs. alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds context: data is cached (5min-1h), derived from CF analytics-engine, contains no PII, and is self-aggregating. This provides additional transparency beyond annotations, though it does not detail rate limits or authentication requirements.

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

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

The description is well-structured and efficient. It front-loads the core output (top tools, packs, total volumes) and time windows, then provides enumerated use cases and additional notes (data source, caching, no PII). No unnecessary words; each sentence serves a purpose.

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

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

Given the low complexity (one optional parameter, no output schema), the description is fully complete. It explains what the tool returns, the available time windows, caching behavior, and data source. No output schema is needed as the description sufficiently conveys the return value structure.

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 single parameter 'window' has 100% schema coverage with enum values and descriptions. The tool description adds practical context by stating the default is '24h' (which the schema does not specify) and explaining the trade-off between shorter and longer windows, enhancing the schema info.

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's purpose: returning trending tools, packs, and call volumes on Pipeworx. It uses specific verbs ('Returns') and distinguishes itself from sibling tools like discover_tools or ask_pipeworx by focusing on aggregated trending data derived from call analytics.

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 (discovering hot data sources, confirming canonical tools, aligning with agent needs). It does not explicitly state when NOT to use this tool or mention alternatives, but the listed use cases give clear guidance on appropriate contexts.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: explains the semantic anchor (Jaccard similarity >= 0.30), partition filter (drops placeholder slugs), fill check (theoretical vs realizable edge, thin_legs[]), and response structure. 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 well-structured: first sentence states core purpose, then breaks into modes with clear headers ('SEMANTIC ANCHOR', 'PARTITION FILTER', 'FILL CHECK'). Every section adds value, though some details like the Jaccard similarity threshold could be more briefly stated. Overall, it earns its length.

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

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

Despite no output schema and only two optional parameters, the description thoroughly explains the response structure (opportunities[] with fields like gap_pp, suggested_trade, reasoning), error handling (skipped_low_similarity, placeholders_filtered), and caveats (realizable_edge_pp ≤ 0 means don't trade). It also references a related tool for custom sizing, covering all necessary 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% with descriptions for both event and topic. The description adds significant meaning beyond schema: provides examples (like 'fed-decision-may-2026' for event and 'Fed rate decision' for topic), explains the behavior difference between modes, and details how each parameter is used (e.g., event walks child markets, topic searches related events). This greatly aids correct invocation.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes: no args for trending scan, event for specific market, and topic for cross-event scanning. It explicitly differentiates from sibling tools like polymarket_fill_risk and polymarket_edges, making its purpose unique.

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

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

The description provides explicit guidance on when to use each mode: call with no args for trending scan, pass event for specific market (recommended for a specific event), pass topic for cross-event scanning (catches patterns single-event misses). It also advises against trading when realizable_edge_pp ≤ 0, giving clear usage boundaries.

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

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

The description provides extensive behavioral detail beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It explains the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), edge calculation (edge_pp_net after slippage, kelly_fraction capped at 0.25, 24h-move warning), caching behavior (1h at KV level), and diagnostic output. 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 comprehensive but lengthy (over 500 words). It is structured with clear sections (model families, opportunity fields, knobs, response top-level) and front-loads the purpose. While every sentence adds value, the density might overwhelm an agent. A slightly more concise version could improve, but the structure is excellent.

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 describes the response structure (by_segment with three categories, fed_candidates/fed_note, _diagnostics with funnel counters). It explains complex behaviors like placeholder-slug filters, per-leg Kelly knobs, and Fed bet exclusion. Given the tool's high complexity, the description leaves no gaps for an agent to interpret the output or 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 description coverage is 100%, so baseline is 3. The description adds value by explaining how parameters like min_edge_pp, slippage_pp, and min_partition_leg_kelly interact with the ranking and filtering logic, and clarifies edge cases (e.g., min_kelly not filtering partition arbs). This goes beyond schema docstrings to connect parameters to the tool's internal behavior.

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

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

The description clearly states it scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It uses a specific verb ('scan'), resource ('Polymarket markets'), and actionable output ('opportunities'), distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker. The phrase 'Built for "what should I bet on today"' explicitly conveys the tool's high-level goal.

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 that the tool is designed for discovering opportunities without paging hundreds of markets, clearly indicating when to use it. It also mentions knobs like min_liquidity, max_spread_pp, and min_partition_leg_kelly that help tailor usage. However, it does not explicitly state when not to use it or direct to alternative sibling tools for specific cases, so it misses a clear '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 read-only, idempotent, non-destructive behavior. The description adds significant context: it reads from daily snapshots, details the response structure (tracked with time-series, expired with lifespan), explains how decay is computed (on |edge_pp_net| from daily closes, not intraday), and notes snapshot gaps. 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 well-structured: purpose, args, response sections, limits. It is front-loaded with the key question. While detailed, every sentence contributes value. Slightly verbose but not to the point of being inefficient.

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

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

Given the complexity and lack of output schema, the description comprehensively covers the response structure (tracked, expired, snapshot_dates) and limits (60-day TTL, snapshot start). No gaps remain for an agent to invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for both parameters (days, window). The description adds default values, clamping, and how they affect the output (lookback, snapshot family). This provides useful 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 the tool's purpose: providing edge persistence and decay telemetry, answering how long an edge has existed and whether it's shrinking. It uses specific verbs and resources (edge persistence telemetry, daily snapshots) and distinguishes the tool from simply showing 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 usage (historical edge analysis) but does not explicitly contrast with sibling tools like polymarket_edges. However, the context of sibling tools and the description of the response (tracked, expired, snapshot dates) makes it clear when to use this tool for persistence/decay analysis.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral context: it walks the order book ladder, returns verdicts (clean|degraded|cannot_fill), and explains basket-mode risks like thin_legs and forced_directional_risk. No contradictions with annotations.

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

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

The description is a single dense paragraph but well-structured with clear section headings (SINGLE-MARKET:, BASKET:). It front-loads the purpose and requirements. Every sentence adds value, no fluff.

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

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

Since there is no output schema, the description fully explains return values: for single-market (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict) and for basket (theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs, max_clean_notional_usd, forced_directional_risk). Also explains the logic behind each.

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 meaningful context beyond schema: explains the difference between single-market and basket modes, default values for side and size_usd, and how size_usd is interpreted differently depending on mode. This enriches agent understanding.

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

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

The description clearly states it checks realizable vs theoretical edge against live order-book depth. It specifies two modes (single-market and basket) and outputs for each. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by being a risk check before acting on their signals.

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 tells when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains when not to rely on theoretical overround and warns about partial basket fills converting arb into directional positions.

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

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

The description adds substantial behavioral context far beyond the readOnly/idempotent annotations: it discloses that spreads are gross of Kalshi fees, that unknown legs are never paired, that null temporal_alignment does not mean aligned, and that returned pairs carry compatibility codes. This gives the agent a realistic picture of reliability and edge cases without contradicting the annotations.

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

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

The description is long, but the length is largely justified by the tool's complexity: modes, disclosure codes, fee treatment, and matching limitations all need explanation. It is front-loaded with the core definition and organized by explicit sections such as 'TWO MODES' and 'SAFETY FIELDS.' Some redundancy with the schema's topic list exists, but not enough to make it bloated.

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

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

With no output schema, the description must explain return values, and it does: per-leg prices, top_spreads_pp, compatibility_warning, compatibility_codes, temporal_alignment, fees_note, and skipped counters. It also covers failure modes and interpretation caveats in enough detail that an agent could invoke the tool and correctly interpret ambiguous results. Nothing essential appears missing.

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

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

Although the schema already documents all three parameters and the topic enum at 100% coverage, the description adds important semantics: topic values are pre-mapped shortcuts, explicit ticker/slug override the topic-mapped side, and both modes run the identical token-overlap matcher. This goes beyond the schema's bare descriptions, so a 4 is warranted.

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

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

The description opens with a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This immediately identifies the tool's unique function and distinguishes it from same-platform edge tools among the siblings. The term 'cross-venue' plus the venue names makes the scope 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 clearly explains the two usage modes ('topic' shorthand vs explicit ticker/slug) and when each is appropriate. It also sets expectations with 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' However, it does not explicitly contrast the tool with sibling alternatives such as polymarket_arbitrage or polymarket_edges, so it stops short of full when-to-use-vs-alternatives 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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds scoping to identifier and behavior on key omission, adding 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?

Three concise sentences, front-loaded with core action, 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 simple tool (1 optional param, no output schema, rich annotations), description covers purpose, usage, scoping, and pairing with siblings completely.

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

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

Single optional parameter 'key' is fully described in schema (100% coverage). Description reiterates the behavior but adds no new semantic information beyond schema.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys, with specific verb-resource pairs and distinguishes from sibling tools remember and forget.

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

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

Provides explicit context for when to use (lookup stored context without re-deriving) and mentions paired tools (remember, forget), but does not explicitly state when not to use.

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

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

Beyond the readOnlyHint annotation, the description adds critical behavioral detail: setting mark_read=true flags events as read, affecting subsequent calls. It also notes that the same feed exists for scripts/dashboards.

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?

Five sentences, each serving a distinct purpose: purpose, return fields, filters, mark_read detail, and alternatives. 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?

The description covers return fields (source, citation_uri, payload), all parameters, side effects, and alternate access. No output schema exists, but the description compensates well.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds value by explaining the mark_read side effect and the unread_only filter, going beyond the schema's basic definitions.

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

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

The description clearly states the verb 'Pull' and the resource 'fired events from your subscription feed'. It distinguishes from sibling tools like list_subscriptions by focusing on alerts/events rather than subscriptions.

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

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

The description explains filtering by type/since, the mark_read behavior, and mentions polling and an alternative API endpoint. However, it does not explicitly state when not to use this tool versus siblings.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details: fan-out to multiple APIs, fallback logic (GDELT→GNews on rate limits/5xx), soft-fail for USPTO due to sunset, and output structure (grouped by source, total_changes count, citation URIs). No contradictions with annotations.

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

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

The description is front-loaded with example queries, then details sources and fallback behavior. It is longer than necessary but each sentence adds value (e.g., addressing API sunset, output format). Minor redundancy could be trimmed, but it's well-organized.

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

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

Despite having no output schema, the description adequately explains the return value (grouped changes, total count, citation URIs). It also covers edge cases (rate limits, sunset). For a multi-source aggregator tool, this is reasonably complete, though further detail on response structure could improve 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%, but the description enriches parameter understanding: 'since' gets examples and recommended values, 'value' explains ticker vs. CIK, and 'type' clarifies only 'company' is supported. This adds practical context beyond the schema's bare definitions.

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

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

The description starts with clear example queries, defines the tool as a 'change feed for a company in the last N days/weeks/months in ONE parallel call,' and lists specific data sources (SEC EDGAR, GDELT, GNews, USPTO). It also distinguishes from sibling tool 'entity_profile,' making the purpose unmistakable.

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

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

The description explicitly contrasts with entity_profile ('Use entity_profile instead when you want the static profile'), gives guidance on the 'since' parameter ('Use "30d" or "1m" for typical monitoring'), and implies when to use (e.g., 'latest on Y', 'updates on Acme'). This is clear and actionable.

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 discloses scoping ('by your identifier'), retention duration (24h anonymous, persistent authenticated), and aligns with annotations (idempotentHint=true, destructiveHint=false). Adds value beyond annotations.

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

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

Every sentence earns its place: purpose, usage, scope, companion tools. No fluff, well-structured, front-loaded with primary action.

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

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

For a write-only tool without output schema, the description covers purpose, usage, parameters, and behavioral context (retention, scoping). Lacks return value info, but acceptable for this type.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaningful examples for keys ('subject_property') and clarifies value is any text, enhancing schema documentation.

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

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

The description explicitly states 'Save data the agent will need to reuse later' with a clear verb (save) and resource (key-value memory). It distinguishes from sibling tools like recall and forget by pairing 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 clear when-to-use guidance ('when you discover something worth carrying forward') with concrete examples. It also notes pairing with recall/forget, but does not explicitly state when not to use.

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

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

The description discloses internal cascading lookups, graceful degradation if GLEIF or OpenFIGI is unavailable, the fact that multiple lookup endpoints are hit, and the behavior of returning EDGAR identifiers even when enrichment fails. It also clarifies that non-equity instruments resolve even though they have no ticker, and explains what happens with ISIN mappings. Combined with annotations declaring readOnly, openWorld, idempotent, and non-destructive hints, the agent has a well-rounded behavioral picture.

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 and quite detailed, but every portion adds operational value: query examples, supported types, behavior for non-equity instruments, ISIN behavior, degradation behavior, and cascading lookup count. It front-loads the most distinguishing information (query patterns and 'use first' rule) before diving into enrichment detail. A 4 rather than 5 because the parameter guidance could be more tightly organized, and the description is verbose enough that an agent must parse a substantial block of text.

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—two entity types, multiple external sources, varying identifier formats, degradation behavior, and no output schema—the description is thorough and covers the important edge cases (non-US issuers, non-equity instruments, drug citations, and fallback behavior). It answers likely agent questions about when to use it and what inputs are valid. There is no output schema, but the description explicitly discloses the return values (CIK, ticker, company_name, LEI, FIGI, RxCUI, ingredient, brand), which substitutes for the missing structured output documentation.

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 already 100%, so the baseline is 3. The description adds extra semantic value by disambiguating the 'value' parameter with a direct example for bonds (pass the issuer exactly as printed, not the full noun phrase) and explaining that trailing security-class words will cause the FIGI lookup to fail. It also clarifies how ISINs map to legal entities through GLEIF, which the schema alone does not convey. Not a 5 because the description is somewhat dense and the parameter guidance is embedded inside a long narrative rather than structured as explicit parameter notes.

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

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

The description opens with concrete query examples and states the core function: resolving user-spoken names to canonical identifiers that other tools require. It explicitly distinguishes itself from siblings by naming the two supported types (company, drug) and the identifier domains covered (CIK, ticker, LEI, FIGI, RxCUIs), which makes the tool's purpose impossible to mistake.

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 rule: "Use FIRST whenever you have a name but need an ID." It also gives detailed routing guidance for non-equity instruments, ISINs, drugs, and when enrichment degrades. This goes well beyond a vague 'use when you need an identifier' and tells the agent exactly when to invoke resolve_entity versus alternatives.

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

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

Describes process: probes with ai_visibility_check, ranks, surfaces most/least recognized. Returns score, confidence, signal density per entity. Annotations already indicate read-only; description adds rich behavioral detail.

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

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

Two sentences, front-loaded with purpose and output. Every sentence adds value; no redundancy or 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 4 parameters fully described in schema, no output schema, and annotations covering safety, the description adequately explains the tool's purpose, process, and return structure.

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 3. Description adds no further parameter meaning beyond summarizing the probe process. No contradiction or omission noted.

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 states specific verb 'compare AI visibility' and resource 'multiple entities', with clear output of ranked list. Distinguishes from sibling 'ai_visibility_check' (single entity) and 'compare_entities' by targeting AI presence.

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

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

Explicitly useful for competitive AI-marketing audits with example. Implicitly for multiple entities, but no explicit when-not-to-use or direct contrast with siblings like ai_visibility_check.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. Description adds behavioral details: fans out across two sources, partial failures degrade gracefully (bundlephobia timeout handled, sources_failed listed), and returns a structured summary. No contradiction.

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

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

The description is a single paragraph that is front-loaded with purpose. Every sentence adds value, though it could be slightly more structured (e.g., bullet points for return fields). Still efficient.

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

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

Given the tool's complexity (multi-source, no output schema), the description thoroughly explains what is returned (summary fields, per-advisory detail, links, alternatives) and partial failure behavior. Slightly light on parameter details, but schema covers those.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by noting scope packages (@types/node) are accepted and version defaults to latest. This extra context raises 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 the tool is a composite check for evaluating adding an npm package, covering license, advisories, version history, and bundle size. It distinguishes from siblings by specifying the NPM-only ecosystem and mentioning alternatives for other ecosystems.

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

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

Explicitly states when to use: when an agent asks about safety/popularity/size or 'what does adding lodash cost me'. It also specifies what not to use for (other ecosystems) and directs to deps.dev:version directly for those.

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 annotations (readOnlyHint, idempotentHint) by disclosing technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K char cap with truncation and flagging. These details help the agent understand constraints and behavior, adding significant value.

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

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

The description is a single paragraph that is concise and front-loaded with the primary purpose. It packs substantial information without being verbose. Minor restructuring could improve readability, but it remains efficient.

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

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

Despite lacking an output schema, the description clearly states the output format: 'top-N passages with character offsets and similarity scores'. It also covers input constraints, use cases, and technical details. For a tool with three simple parameters, the description is comprehensive and leaves no major gaps.

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

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

All three parameters are described in the schema with 100% coverage. The description adds context to the 'text' parameter (e.g., 'max ~200K chars') and provides natural-language query examples for 'query', enhancing understanding beyond the schema descriptions. The default for 'limit' is already in the schema.

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

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

The description clearly identifies the tool as performing semantic search inside a fetched record. It specifies the action ('search'), the resource ('a fetched record'), and the output ('passages with character offsets and similarity scores'). It distinguishes from sibling tools like 'search_words' by emphasizing internal search and pairs with 'ask_pipeworx_grounded', showing clear differentiation.

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

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

The description explicitly states when to use the tool: 'Use when the record is too big to cram into the prompt'. It also provides a complementary tool ('ask_pipeworx_grounded') for alternative use. While it does not list specific cases for avoidance, the positive guidance is strong and 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 provide readOnlyHint, idempotentHint, etc. Description adds useful behavioral context: returns up to `limit` entries with specific fields, input types (English, kanji, kana, romaji). 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?

Two sentences, front-loaded with purpose and input flexibility, then return format and use cases. No unnecessary words, very efficient.

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

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

No output schema, but description thoroughly explains return fields (headword, common word flag, JLPT level, readings, meanings with senses and POS). Schema covers both parameters. Complete enough for effective use.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds extra meaning: keyword can be English, kanji, kana, or romaji, and limit defaults to 10. This goes beyond the schema description.

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

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

The description clearly states the tool searches the Jisho.org Japanese-English dictionary, specifies the resource and action, and distinguishes it from sibling tools which are different in scope.

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

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

Explicitly states use cases: translate, look up a kanji/kana word, or find Japanese words for an English concept. Does not explicitly mention when not to use or alternatives, but context is clear.

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

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

Beyond annotations (which indicate idempotent, non-destructive, non-read-only), the description discloses behaviors like the 10/day SMS cap, webhook auto-disable after 10 consecutive failures, and the need for phone verification. This adds significant context for the agent.

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, starting with the main purpose, then types, then delivery. It is thorough but may be slightly long; however, every sentence adds value.

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

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

Given the tool's complexity (3 parameters, nested objects, no output schema), the description covers prerequisites, type-specific parameters, delivery mechanics (feed always on, email, SMS, webhook with signing), rate limits, and error handling (auto-disable). No gaps remain.

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

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

Although the input schema has 100% coverage, the description adds substantial meaning: for each type, it provides detailed examples and purpose (e.g., 'sec_8k: filings matching ticker + item codes'); for delivery, it explains webhook signing and auto-disable. This goes well beyond the schema.

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

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

The description clearly states the tool's function: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It specifies the resource (subscription), the action (create), and distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description provides prerequisites ('Requires a Pipeworx OAuth account'), lists supported types with examples, and details delivery channels. It does not explicitly contrast with sibling tools, but the context is clear enough for an agent to decide when to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds valuable behavioral context: it is the onboarding entry point, returns categorized example questions with tool/argument shapes, and can be called with no arguments for full spread or with a topic to focus. This goes beyond the annotations without contradicting them.

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

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

The description is a single paragraph starting with a list of example user intents, which is slightly redundant but still adds context. It efficiently conveys purpose, usage, and output structure in about 100 words. Could be more structured (e.g., bullet points for topic options), but overall concise 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 lack of an output schema, the description adequately explains that the return is category-bucketed example questions with tool and argument shapes. It covers parameter behavior and states the tool's role as an onboarding entry point. No critical missing information for an agent to use it effectively.

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

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

Schema description coverage is 100% and the schema already describes the optional topic parameter. The description enhances this by providing concrete examples ('e.g. 'finance', 'pharma', 'betting') and explaining the behavior difference between omitting (full spread) and passing a topic (focus). This adds meaning beyond the schema alone.

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

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

The description clearly states the tool as the onboarding entry point that returns category-bucketed example questions with exact tool + argument shape, explicitly distinguishing it from siblings by advising 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' The verb and resource are specific and distinct from siblings like ask_pipeworx or discover_tools.

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

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

The description gives clear context for when to use: 'when you do not yet know what Pipeworx can do' and 'to learn how to call the meta-tools.' It also explains how to pass an optional topic to focus. However, it does not explicitly state when not to use it or list alternative tools for specific scenarios, though the context implies usage for initial exploration.

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 significant context beyond annotations: ownership enforcement, soft deactivation (not deletion), and historical event availability. Matches annotations (readOnlyHint=false, destructiveHint=false).

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

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

Three sentences with clear front-loading of purpose, followed by constraint and behavioral detail. 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?

For a simple single-parameter tool without output schema, the description fully covers purpose, usage constraints, and outcome.

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

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

Schema coverage is 100% and description succinctly adds that the id is returned by subscribe, which provides necessary source context.

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 'Cancel' and the resource 'subscription by id'. It is distinct from sibling tools like subscribe and list_subscriptions.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions') and explains the deactivation behavior, but does not explicitly mention when not to use or alternatives.

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

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

The description goes far beyond the readOnly/openWorld/idempotent annotations by disclosing the routing behavior (financial vs non-financial), the full verdict vocabulary and their meanings, the distinction between 'could_not_verify' (no evidence) and 'unsupported' (no coverage), and the inclusion of citations. It also explicitly warns callers not to treat 'could_not_verify' as evidence for or against a claim, which is critical behavioral nuance.

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

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

The description is thorough but verbose, at over 200 words for a simple 2-param tool. It front-loads the purpose and includes valuable behavioral details, but the many example phrases, routing details, and caller warning could be tightened into a more concise structure while preserving the necessary nuance.

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

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

Despite having no output schema, the description fully explains return values: verdict, actual value with pipeworx:// citation, and reasoning. It also clearly details error semantics ('could_not_verify' with verification_error) and the distinction from 'unsupported', ensuring an agent can safely invoke and interpret results without additional external documentation.

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

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

The input schema already fully describes both parameters, including the claim example and the tolerance_pct semantics, default, and override guidance. The tool description adds little beyond inline examples already covered by the schema; with 100% schema description coverage, a baseline score of 3 is appropriate.

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

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

The description opens with a clear, specific purpose: 'natural-language claim verification against authoritative sources' and lists example query phrasings to anchor it. It distinguishes itself from siblings by describing the structured SEC EDGAR/XBRL fast path for company-financial claims and automatic fallback to a grounded pipeline for any other factual claim, making clear it is the dedicated fact-checking tool.

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

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

The description explicitly instructs 'Use whenever the agent needs to check whether something a user said is factually correct' and explains coverage of both company-financial and non-financial claims. It does not explicitly name when-not-to-use alternatives, but the statement 'Replaces 4–6 sequential calls' gives a strong strong indication to prefer this tool over manual multi-step lookups.

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